Skip to content

Commit 05271de

Browse files
bradpottsbradpotts
committed
docs: expand AI agent guidance & workflows
Add detailed agent roles, handoff rules, and repository snapshot to docs. Updates to AGENTS.md, CODEX.md, COPILOT.md, JULES.md, CONTRIBUTING.md, and README.md introduce a repository snapshot, clarified authority model (including ChatGPT support role), PR/handoff and validation expectations, allowed/restricted work for Copilot and Jules, commit message conventions for maintenance, and contributor Code of Conduct and license guidance. These changes aim to standardize agent responsibilities, verification gates (npm run check), and PR handoff information for clearer maintenance and release workflows.
1 parent e4516e4 commit 05271de

6 files changed

Lines changed: 143 additions & 2 deletions

File tree

‎AGENTS.md‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,48 @@
11
# AGENTS.md - spectre-init
22

3+
## Repository Snapshot
4+
5+
| Field | Value |
6+
|-------|-------|
7+
| Project team | `project-shell` |
8+
| Repository role | Spectre project scaffolding CLI |
9+
| Package/artifact | `@phcdevworks/spectre-init` |
10+
| Validation gate | `npm run check` |
11+
12+
## Standard Authority Model
13+
14+
| Agent | Role | Authority |
15+
|-------|------|-----------|
16+
| Claude Code | Lead implementation and validation | [CLAUDE.md](CLAUDE.md) |
17+
| OpenAI Codex | Documentation, release readiness, stabilization, and repo hygiene | [CODEX.md](CODEX.md) |
18+
| ChatGPT | Strategy, coordination, prompt design, and external review | Support only |
19+
| GitHub Copilot | Development assistance | [COPILOT.md](COPILOT.md) |
20+
| Google Jules | Bounded automated maintenance | [JULES.md](JULES.md) |
21+
22+
Bradley Potts holds final authority for commits, merges, tags, publishing, and
23+
releases.
24+
25+
## Standard Handoff
26+
27+
Every AI-prepared change should report files changed, validation performed,
28+
public behavior or contract impact, and unresolved risks. Do not edit generated
29+
outputs directly. Do not update [CHANGELOG.md](CHANGELOG.md) unless the change
30+
is release-relevant.
31+
332
## AI Operating Model
433

534
This is the central AI coordination document for the repository. Agent-specific
635
files may add tool-local guidance, but they must not override the role
736
boundaries below.
837

9-
This repository uses a four-agent AI operating model with defined,
38+
This repository uses a five-agent AI operating model with defined,
1039
non-overlapping roles:
1140

1241
| Agent | Role |
1342
| ------------------ | ---------------------------------------------------------------------- |
1443
| **Claude Code** | Lead developer - primary implementation, architecture, tests |
1544
| **OpenAI Codex** | Documentation, releases, production stabilization, repo hygiene |
45+
| **ChatGPT** | Strategy, coordination, prompt design, and external review - support only |
1646
| **GitHub Copilot** | General development assistance (in-editor suggestions) |
1747
| **Google Jules** | Automated maintenance - small fixes, dependency updates, micro-patches |
1848

‎CODEX.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# CODEX.md - spectre-init
22

3+
## Role
4+
35
OpenAI Codex serves as the secondary production-readiness and release-support
46
agent for this repository. Claude Code remains the primary AI developer and
57
`CLAUDE.md` remains the authoritative working guide.
@@ -63,6 +65,12 @@ Before a release handoff, Codex should verify:
6365
- Keep Jules guidance aligned between root `AGENTS.md` and `JULES.md`.
6466
- Keep automated review configuration aligned with the repository constraints.
6567

68+
## Pull Request Creation
69+
70+
Follow the shared PR requirements in `AGENTS.md`. When Codex prepares a PR
71+
handoff, include the validation status and any unresolved release risk in the
72+
summary.
73+
6674
## Standard Handoff Format
6775

6876
Use this shape when reporting production readiness:

‎CONTRIBUTING.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,12 @@ npm run check
2727

2828
## Pull Requests
2929

30-
Describe the user-facing scaffolding change, call out template updates, and include the commands you ran.
30+
Describe the user-facing scaffolding change, call out template updates, and include the commands you ran. Populate all sections of the PR template.
31+
32+
## Code of Conduct
33+
34+
By participating in this project, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
35+
36+
## License
37+
38+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎COPILOT.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,11 +29,40 @@ live in `AGENTS.md`.
2929
- Do not take ownership from Claude Code or Codex.
3030
- Do not make release decisions, publish, merge, or tag.
3131

32+
## Allowed Work
33+
34+
- Small and medium implementation support tasks.
35+
- Focused refactors that reduce risk and improve readability.
36+
- Test suggestions for CLI behavior and template generation.
37+
- README and workflow/template updates when appropriate.
38+
39+
## Restricted Work
40+
41+
- Do not replace Claude Code as lead implementation owner.
42+
- Do not override Codex release-readiness findings.
43+
- Do not publish, merge, tag, or release.
44+
- Do not broaden package scope beyond CLI scaffolding.
45+
46+
## Validation
47+
48+
Follow the shared verification gate in `AGENTS.md`. If `npm run check` fails, report the
49+
failing step and likely cause, then suggest the smallest safe fix.
50+
51+
## Documentation Expectations
52+
53+
Keep `README.md`, `CHANGELOG.md`, and GitHub templates consistent with current
54+
CLI behavior and template contents.
55+
3256
## Pull Request Creation
3357

3458
Follow the shared PR requirements in `AGENTS.md`. Include validation results
3559
and release impact notes for Codex handoff.
3660

61+
## PR and Issue Support
62+
63+
Support package-boundary review, public API impact notes, validation status,
64+
and release impact visibility for Codex handoff.
65+
3766
## Source of Detailed Guidance
3867

3968
Primary Copilot guidance lives in `.github/copilot-instructions.md`.

‎JULES.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,19 @@ Claude Code remains the lead implementation agent. Codex owns documentation,
1515
release readiness, production stabilization, repo hygiene, and config
1616
standardization. Bradley Potts remains the final release and merge authority.
1717

18+
Jules does not own feature work, architecture changes, public CLI contract
19+
changes, large refactors, documentation governance, release decisions, or
20+
AI-agent governance.
21+
22+
## Operating Principles
23+
24+
1. Read `AGENTS.md` before taking any action.
25+
2. Defer to `CLAUDE.md` for development authority.
26+
3. Follow the shared source, validation, and PR rules in `AGENTS.md`.
27+
4. Commit and push only when all validation gates pass clean.
28+
5. If a gate fails and cannot be safely resolved within scope, stop and report
29+
the blocker instead of committing a broken state.
30+
1831
## Allowed Maintenance
1932

2033
- Dependency micro-updates generated through Dependabot or equivalent tooling.
@@ -38,3 +51,24 @@ npm run check
3851

3952
If validation fails, stop and hand off the failure summary instead of widening
4053
the change.
54+
55+
## Pull Request Creation
56+
57+
Follow the shared PR requirements in `AGENTS.md`. Jules PRs should also state
58+
which maintenance category was executed.
59+
60+
## Commit Authority
61+
62+
Jules commits and pushes autonomously when all validation gates pass clean.
63+
Jules must not:
64+
- reset or discard changes it did not make
65+
- force-push or rewrite history
66+
- commit any state where a validation gate fails
67+
- absorb unrelated working-tree changes into its commit
68+
69+
### Commit message format
70+
71+
- Dependency update: `chore(spectre-init): bump <package> to <version>`
72+
- Doc fix: `docs(spectre-init): <description of fix>`
73+
- Config cleanup: `chore(spectre-init): <description of cleanup>`
74+
- Starter hygiene: `chore(spectre-init): <description of update>`

‎README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,37 @@
11
# @phcdevworks/spectre-init
22

3+
## Repository Snapshot
4+
5+
| Field | Value |
6+
|-------|-------|
7+
| Project team | `project-shell` |
8+
| Repository role | Spectre project scaffolding CLI |
9+
| Package/artifact | `@phcdevworks/spectre-init` |
10+
| Current version/status | 1.0.0 |
11+
12+
## Standard Workflow
13+
14+
1. Read [AGENTS.md](AGENTS.md), then the agent-specific guide for the task.
15+
2. Check [TODO.md](TODO.md) and [ROADMAP.md](ROADMAP.md) for current scope.
16+
3. Make the smallest repo-local change that satisfies the task.
17+
4. Run `npm run check` when validation is required or practical.
18+
5. Update docs and [CHANGELOG.md](CHANGELOG.md) only when behavior, public
19+
contracts, or release-relevant metadata changed.
20+
21+
## Documentation Map
22+
23+
| Guide | Path |
24+
|-------|------|
25+
| Agent rules | [AGENTS.md](AGENTS.md) |
26+
| Claude Code | [CLAUDE.md](CLAUDE.md) |
27+
| Codex | [CODEX.md](CODEX.md) |
28+
| Copilot | [COPILOT.md](COPILOT.md) |
29+
| Jules | [JULES.md](JULES.md) |
30+
| Roadmap | [ROADMAP.md](ROADMAP.md) |
31+
| Todo | [TODO.md](TODO.md) |
32+
| Changelog | [CHANGELOG.md](CHANGELOG.md) |
33+
| Security | [SECURITY.md](SECURITY.md) |
34+
335
[![npm version](https://img.shields.io/npm/v/@phcdevworks/spectre-init.svg)](https://www.npmjs.com/package/@phcdevworks/spectre-init)
436
[![CI](https://img.shields.io/github/actions/workflow/status/phcdevworks/spectre-init/ci.yml?branch=main&label=CI)](https://github.com/phcdevworks/spectre-init/actions/workflows/ci.yml)
537
[![License](https://img.shields.io/github/license/phcdevworks/spectre-init)](LICENSE)

0 commit comments

Comments
 (0)