my-opencode 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +163 -0
- package/agents/architect.md +30 -0
- package/agents/code-reviewer.md +29 -0
- package/agents/executor.md +30 -0
- package/agents/fullstack-dev.md +53 -0
- package/agents/spec-writer.md +37 -0
- package/agents/team-lead.md +60 -0
- package/agents/tech-writer.md +30 -0
- package/agents/test-engineer.md +30 -0
- package/agents/verifier.md +33 -0
- package/bin/cli.js +272 -0
- package/opencode.json +164 -0
- package/package.json +44 -0
- package/skills/adr/SKILL.md +91 -0
- package/skills/adr/references/templates.md +100 -0
- package/skills/adr/scripts/README.md +5 -0
- package/skills/dev-flow/SKILL.md +188 -0
- package/skills/dev-flow/references/code-phase.md +72 -0
- package/skills/dev-flow/references/contract-phase.md +81 -0
- package/skills/dev-flow/references/verify-phase.md +129 -0
- package/skills/dev-flow/scripts/README.md +3 -0
- package/skills/docs-gen/SKILL.md +162 -0
- package/skills/docs-gen/references/doc-styles.md +216 -0
- package/skills/docs-gen/scripts/README.md +5 -0
- package/skills/orchestrate/SKILL.md +112 -0
- package/skills/orchestrate/references/orchestration-patterns.md +56 -0
- package/skills/pr-review/SKILL.md +110 -0
- package/skills/pr-review/references/review-dimensions.md +117 -0
- package/skills/pr-review/references/security-checklist.md +122 -0
- package/skills/pr-review/scripts/README.md +5 -0
- package/skills/test-gen/SKILL.md +143 -0
- package/skills/test-gen/references/framework-detection.md +105 -0
- package/skills/test-gen/references/test-patterns.md +260 -0
- package/skills/test-gen/scripts/README.md +5 -0
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dev-flow
|
|
3
|
+
description: |
|
|
4
|
+
Contract-first development workflow: contract → code → verify → fix (loop).
|
|
5
|
+
Drives development from persistent specifications, enabling parallel frontend/backend work.
|
|
6
|
+
Use PROACTIVELY when implementing features, fixing bugs, refactoring, or making code changes.
|
|
7
|
+
Triggers on: "implement", "feature", "fix bug", "refactor", "add", "change", "build"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Development Flow
|
|
11
|
+
|
|
12
|
+
Contract-first development workflow. Writes persistent specifications before coding, so frontend and backend can work in parallel from the same contract.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- Implementing a new feature
|
|
17
|
+
- Fixing a bug
|
|
18
|
+
- Refactoring existing code
|
|
19
|
+
- Making any non-trivial code change
|
|
20
|
+
|
|
21
|
+
## Phase Overview
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
[Phase 0: Architecture — ADR (optional)]
|
|
25
|
+
│
|
|
26
|
+
v
|
|
27
|
+
Phase 1: Contract ──→ docs/specs/<feature>/ (persistent, committed)
|
|
28
|
+
│ Frontend & Backend can start in parallel
|
|
29
|
+
v
|
|
30
|
+
Phase 2: Code
|
|
31
|
+
│
|
|
32
|
+
v
|
|
33
|
+
Phase 3: Verify ──→ against acceptance criteria from Phase 1
|
|
34
|
+
│
|
|
35
|
+
v
|
|
36
|
+
[Fix loop] → back to Phase 2 (max 3 retries)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Phase 0: Architecture (Optional)
|
|
40
|
+
|
|
41
|
+
**When:** An architectural decision needs recording (tech choice, structural change, cross-team impact).
|
|
42
|
+
|
|
43
|
+
**Output:** `docs/adr/NNNN-title.md` — Architecture Decision Record
|
|
44
|
+
|
|
45
|
+
**Agent:** architect
|
|
46
|
+
|
|
47
|
+
See `skills/adr/SKILL.md` for ADR workflow and template.
|
|
48
|
+
|
|
49
|
+
→ Then proceed to Phase 1 with the ADR as architectural context.
|
|
50
|
+
|
|
51
|
+
## Phase 1: Contract
|
|
52
|
+
|
|
53
|
+
**Goal:** Produce a persistent specification that records consensus and enables parallel implementation.
|
|
54
|
+
|
|
55
|
+
**Output (persistent, committed to repo):**
|
|
56
|
+
```
|
|
57
|
+
docs/specs/<feature>/
|
|
58
|
+
├── README.md # Requirements, ACs, API contract, data model
|
|
59
|
+
├── api-spec.yaml # OpenAPI spec (if applicable)
|
|
60
|
+
└── data-model.md # Schema definitions (if applicable)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Steps
|
|
64
|
+
1. **Analyze** — Read relevant files, existing ADRs, understand context
|
|
65
|
+
2. **Check ADRs** — Are there existing ADRs that constrain this feature? Reference them.
|
|
66
|
+
3. **Specify** — Write the contract document:
|
|
67
|
+
- Functional requirements (RFC 2119: MUST/SHOULD/MAY)
|
|
68
|
+
- Acceptance criteria (GIVEN/WHEN/THEN)
|
|
69
|
+
- API contract (endpoints, request/response schemas)
|
|
70
|
+
- Data model (entities, fields, types, constraints)
|
|
71
|
+
- Out of scope (explicit exclusions)
|
|
72
|
+
4. **Review** — Present contract to user for approval
|
|
73
|
+
|
|
74
|
+
### Contract Document Template
|
|
75
|
+
```markdown
|
|
76
|
+
# Feature: <title>
|
|
77
|
+
|
|
78
|
+
## Requirements
|
|
79
|
+
FR-1: System MUST <behavior>
|
|
80
|
+
|
|
81
|
+
## Acceptance Criteria
|
|
82
|
+
- GIVEN <context> WHEN <action> THEN <result>
|
|
83
|
+
|
|
84
|
+
## API Contract
|
|
85
|
+
POST /api/xxx
|
|
86
|
+
Request: { field: type }
|
|
87
|
+
Response: { field: type }
|
|
88
|
+
|
|
89
|
+
## Data Model
|
|
90
|
+
| Entity | Field | Type | Constraints |
|
|
91
|
+
|
|
92
|
+
## Out of Scope
|
|
93
|
+
- <explicit exclusions>
|
|
94
|
+
|
|
95
|
+
## Architecture
|
|
96
|
+
References: ADR-001, ADR-003
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Agent: spec-writer
|
|
100
|
+
- Tools: Read, Grep, Glob, Bash, Write, Edit
|
|
101
|
+
- Writes to `docs/specs/<feature>/`, NOT to `.handoffs/`
|
|
102
|
+
|
|
103
|
+
See `references/contract-phase.md` for detailed contract workflow.
|
|
104
|
+
|
|
105
|
+
## Phase 2: Code
|
|
106
|
+
|
|
107
|
+
**Goal:** Implement the contract. Frontend and backend can proceed independently.
|
|
108
|
+
|
|
109
|
+
### Steps
|
|
110
|
+
1. **Read contract** — Load `docs/specs/<feature>/README.md` and referenced ADRs
|
|
111
|
+
2. **Implement** — Write code following the contract and project conventions
|
|
112
|
+
3. **Self-review** — Verify code matches the contract before moving on
|
|
113
|
+
|
|
114
|
+
### Key Principle
|
|
115
|
+
The contract in `docs/specs/` is the source of truth. If implementation reveals
|
|
116
|
+
issues with the contract, update the contract first, then code.
|
|
117
|
+
|
|
118
|
+
### Handoff (`.handoffs/dev-flow/code.md`)
|
|
119
|
+
Lightweight — references contract rather than duplicating it:
|
|
120
|
+
- Files changed
|
|
121
|
+
- Deviations from contract (with rationale)
|
|
122
|
+
- Pending items
|
|
123
|
+
|
|
124
|
+
### Agent: executor
|
|
125
|
+
- Tools: Read, Write, Edit, Bash, Grep, Glob
|
|
126
|
+
- Full read/write access
|
|
127
|
+
|
|
128
|
+
See `references/code-phase.md` for detailed coding workflow.
|
|
129
|
+
|
|
130
|
+
## Phase 3: Verify
|
|
131
|
+
|
|
132
|
+
**Goal:** Verify implementation against the acceptance criteria from Phase 1.
|
|
133
|
+
|
|
134
|
+
### Steps
|
|
135
|
+
1. **Lint** — Run linter
|
|
136
|
+
2. **Typecheck** — Run type checker if applicable
|
|
137
|
+
3. **Test** — Run tests, verify acceptance criteria are met
|
|
138
|
+
4. **Build** — Verify project builds
|
|
139
|
+
|
|
140
|
+
If any step fails → enter fix loop (back to Phase 2).
|
|
141
|
+
|
|
142
|
+
### Handoff (`.handoffs/dev-flow/verify.md`)
|
|
143
|
+
- Lint/typecheck/test/build results
|
|
144
|
+
- Acceptance criteria pass/fail from contract
|
|
145
|
+
- Final verdict: pass / needs fix
|
|
146
|
+
|
|
147
|
+
### Agent: verifier
|
|
148
|
+
- Tools: Read, Grep, Glob, Bash
|
|
149
|
+
- Read-only + execute tests
|
|
150
|
+
|
|
151
|
+
See `references/verify-phase.md` for detailed verification workflow.
|
|
152
|
+
|
|
153
|
+
## Fix Loop
|
|
154
|
+
|
|
155
|
+
If verification fails:
|
|
156
|
+
1. Read contract and verification output to understand failures
|
|
157
|
+
2. Fix issues (Phase 2)
|
|
158
|
+
3. Re-verify (Phase 3)
|
|
159
|
+
4. Max 3 iterations
|
|
160
|
+
|
|
161
|
+
## Quick Start
|
|
162
|
+
|
|
163
|
+
**Simple change (≤3 files, well-understood):**
|
|
164
|
+
```
|
|
165
|
+
Phase 0: Skip (no ADR needed)
|
|
166
|
+
Phase 1: Quick contract → Phase 2: Code → Phase 3: Verify
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
**Complex change (new feature, architectural impact):**
|
|
170
|
+
```
|
|
171
|
+
Phase 0: ADR first → Phase 1: Full contract with user review
|
|
172
|
+
→ Phase 2: Code (frontend + backend parallel) → Phase 3: Verify
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Artifact Summary
|
|
176
|
+
|
|
177
|
+
| Artifact | Location | Persistent | Purpose |
|
|
178
|
+
|----------|----------|------------|---------|
|
|
179
|
+
| ADR | `docs/adr/NNNN-title.md` | ✅ Committed | Architecture decisions |
|
|
180
|
+
| Contract | `docs/specs/<feature>/` | ✅ Committed | Requirements, ACs, API contract |
|
|
181
|
+
| Code handoff | `.handoffs/dev-flow/code.md` | ❌ Temporary | Implementation notes |
|
|
182
|
+
| Verify report | `.handoffs/dev-flow/verify.md` | ❌ Temporary | Verification results |
|
|
183
|
+
|
|
184
|
+
## Related Skills
|
|
185
|
+
|
|
186
|
+
- `adr` — Architecture Decision Records (Phase 0)
|
|
187
|
+
- `test-gen` — Generate tests from acceptance criteria
|
|
188
|
+
- `pr-review` — Review code against the contract
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Code Phase — Detailed Workflow
|
|
2
|
+
|
|
3
|
+
## Entry Conditions
|
|
4
|
+
|
|
5
|
+
- Plan handoff exists at `.handoffs/dev-flow/plan.md`
|
|
6
|
+
- Plan has been reviewed and approved by user
|
|
7
|
+
|
|
8
|
+
## Process
|
|
9
|
+
|
|
10
|
+
### 1. Read the Plan
|
|
11
|
+
- Load `.handoffs/dev-flow/plan.md`
|
|
12
|
+
- Understand the implementation steps
|
|
13
|
+
- Note which files to modify and how
|
|
14
|
+
|
|
15
|
+
### 2. Setup
|
|
16
|
+
- For each file to be modified, read the current content first
|
|
17
|
+
- Understand the existing code structure
|
|
18
|
+
|
|
19
|
+
### 3. Implement Step by Step
|
|
20
|
+
- Follow the implementation steps from the plan
|
|
21
|
+
- After each step, verify the change is coherent
|
|
22
|
+
- If you discover something the plan missed, note the deviation
|
|
23
|
+
|
|
24
|
+
### 4. Follow Project Conventions
|
|
25
|
+
- Look at neighboring files for style/pattern reference
|
|
26
|
+
- Match existing code style (naming, imports, formatting)
|
|
27
|
+
- Follow the project's established patterns
|
|
28
|
+
|
|
29
|
+
### 5. Self-Review
|
|
30
|
+
Before moving to Verify phase:
|
|
31
|
+
- [ ] All planned changes implemented
|
|
32
|
+
- [ ] No dead code or commented-out code
|
|
33
|
+
- [ ] Error handling in place
|
|
34
|
+
- [ ] Edge cases considered
|
|
35
|
+
- [ ] No secrets or debug logs committed
|
|
36
|
+
- [ ] Changes follow project conventions
|
|
37
|
+
|
|
38
|
+
### 6. Output Handoff
|
|
39
|
+
|
|
40
|
+
Write to `.handoffs/dev-flow/code.md`:
|
|
41
|
+
|
|
42
|
+
```markdown
|
|
43
|
+
# Code Changes: <title>
|
|
44
|
+
|
|
45
|
+
## Summary
|
|
46
|
+
<overview of what was changed>
|
|
47
|
+
|
|
48
|
+
## Files Changed
|
|
49
|
+
| File | Action | Description |
|
|
50
|
+
|------|--------|-------------|
|
|
51
|
+
| src/foo.ts | Modified | Added feature logic |
|
|
52
|
+
|
|
53
|
+
## Deviations from Plan
|
|
54
|
+
- <any changes from the original plan, with rationale>
|
|
55
|
+
|
|
56
|
+
## Pending Items
|
|
57
|
+
- <things that need attention before completion>
|
|
58
|
+
|
|
59
|
+
## Self-Review Checklist
|
|
60
|
+
- [ ] All changes tested locally
|
|
61
|
+
- [ ] No regressions introduced
|
|
62
|
+
- [ ] Code follows project conventions
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Anti-Patterns
|
|
66
|
+
|
|
67
|
+
- ❌ Modifying files without reading them first
|
|
68
|
+
- ❌ Copy-pasting code without understanding
|
|
69
|
+
- ❌ Leaving debug code, console.log, TODO comments
|
|
70
|
+
- ❌ Ignoring error handling
|
|
71
|
+
- ❌ Making unrelated changes
|
|
72
|
+
- ❌ Skipping the plan handoff read
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Contract Phase — Detailed Workflow
|
|
2
|
+
|
|
3
|
+
The Contract phase replaces the old Plan phase. It produces **persistent, committed** specification documents instead of temporary handoffs.
|
|
4
|
+
|
|
5
|
+
## Entry Conditions
|
|
6
|
+
|
|
7
|
+
- User request received (feature, bug, refactor)
|
|
8
|
+
- Dev-flow skill activated
|
|
9
|
+
- Optional: ADRs exist in `docs/adr/` that constrain this feature
|
|
10
|
+
|
|
11
|
+
## Analysis Process
|
|
12
|
+
|
|
13
|
+
### 1. Understand the Request
|
|
14
|
+
- Read the user's request carefully
|
|
15
|
+
- Ask clarifying questions if ambiguous (one at a time, with rationale)
|
|
16
|
+
- Identify the core goal, not just the surface request
|
|
17
|
+
|
|
18
|
+
### 2. Check Existing ADRs
|
|
19
|
+
- Read `docs/adr/README.md` for index
|
|
20
|
+
- Identify relevant ADRs that constrain or inform this feature
|
|
21
|
+
- Reference ADR numbers in the contract document
|
|
22
|
+
|
|
23
|
+
### 3. Explore the Codebase
|
|
24
|
+
- Read relevant files to understand current state
|
|
25
|
+
- Use Grep/Glob to find related code
|
|
26
|
+
- Identify patterns and conventions
|
|
27
|
+
|
|
28
|
+
### 4. Specify the Contract
|
|
29
|
+
|
|
30
|
+
Write to `docs/specs/<feature>/README.md`:
|
|
31
|
+
|
|
32
|
+
```markdown
|
|
33
|
+
# Feature: <title>
|
|
34
|
+
|
|
35
|
+
## Requirements
|
|
36
|
+
FR-1: System MUST <behavior>
|
|
37
|
+
FR-2: System SHOULD <behavior>
|
|
38
|
+
FR-3: System MAY <behavior>
|
|
39
|
+
|
|
40
|
+
## Acceptance Criteria
|
|
41
|
+
- GIVEN <context> WHEN <action> THEN <expected result>
|
|
42
|
+
|
|
43
|
+
## API Contract
|
|
44
|
+
- POST /api/xxx
|
|
45
|
+
Request: { field: type }
|
|
46
|
+
Response: { field: type }
|
|
47
|
+
|
|
48
|
+
## Data Model
|
|
49
|
+
| Entity | Field | Type | Constraints |
|
|
50
|
+
|
|
51
|
+
## Out of Scope
|
|
52
|
+
- <explicit exclusions>
|
|
53
|
+
|
|
54
|
+
## Architecture References
|
|
55
|
+
- ADR-001: <title>
|
|
56
|
+
- ADR-003: <title>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### 5. User Review
|
|
60
|
+
- Present contract to user
|
|
61
|
+
- Ask: "Does this contract look correct? Ready to implement?"
|
|
62
|
+
- Wait for approval before proceeding to Code phase
|
|
63
|
+
|
|
64
|
+
## Key Differences from Old Plan Phase
|
|
65
|
+
|
|
66
|
+
| Aspect | Old Plan (handoff) | New Contract (persistent) |
|
|
67
|
+
|--------|-------------------|--------------------------|
|
|
68
|
+
| Location | `.handoffs/dev-flow/plan.md` | `docs/specs/<feature>/README.md` |
|
|
69
|
+
| Persistence | Temporary (gitignored) | Committed to repo |
|
|
70
|
+
| Audience | Next phase only | All current and future developers |
|
|
71
|
+
| Granularity | Implementation steps | Requirements + ACs + API |
|
|
72
|
+
| Parallel work | Not supported | Frontend/backend can work in parallel |
|
|
73
|
+
| ADR integration | None | Explicit reference |
|
|
74
|
+
|
|
75
|
+
## Anti-Patterns
|
|
76
|
+
|
|
77
|
+
- ❌ Writing contracts in `.handoffs/` instead of `docs/specs/`
|
|
78
|
+
- ❌ Over-specifying implementation details (that's for Code phase)
|
|
79
|
+
- ❌ Ignoring existing ADRs
|
|
80
|
+
- ❌ Writing contracts in a different doc per code phase (update the single contract)
|
|
81
|
+
- ❌ Skipping user review for complex features
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# Verify Phase — Detailed Workflow
|
|
2
|
+
|
|
3
|
+
## Entry Conditions
|
|
4
|
+
|
|
5
|
+
- Code handoff exists at `.handoffs/dev-flow/code.md`
|
|
6
|
+
- Code changes have been implemented
|
|
7
|
+
|
|
8
|
+
## Process
|
|
9
|
+
|
|
10
|
+
Run verification steps in order. Stop at first failure and report.
|
|
11
|
+
|
|
12
|
+
### 1. Detect Project Type
|
|
13
|
+
- Look for `package.json` → Node.js project
|
|
14
|
+
- Look for `Cargo.toml` → Rust project
|
|
15
|
+
- Look for `pyproject.toml` / `requirements.txt` → Python project
|
|
16
|
+
- Look for `go.mod` → Go project
|
|
17
|
+
- Use `ls` on project root to detect
|
|
18
|
+
|
|
19
|
+
### 2. Run Lint
|
|
20
|
+
```
|
|
21
|
+
# Node
|
|
22
|
+
npm run lint # or yarn lint, pnpm lint
|
|
23
|
+
|
|
24
|
+
# Rust
|
|
25
|
+
cargo clippy
|
|
26
|
+
|
|
27
|
+
# Python
|
|
28
|
+
ruff check . # or flake8, pylint
|
|
29
|
+
|
|
30
|
+
# Go
|
|
31
|
+
go vet ./...
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
**Pass condition:** Exit code 0, no errors.
|
|
35
|
+
**Fail:** Record lint errors in handoff.
|
|
36
|
+
|
|
37
|
+
### 3. Run Typecheck (if applicable)
|
|
38
|
+
```
|
|
39
|
+
# TypeScript
|
|
40
|
+
npx tsc --noEmit # or npm run typecheck
|
|
41
|
+
|
|
42
|
+
# Rust
|
|
43
|
+
cargo check
|
|
44
|
+
|
|
45
|
+
# Python (pyright/mypy)
|
|
46
|
+
pyright .
|
|
47
|
+
mypy .
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
**Pass condition:** Exit code 0, no type errors.
|
|
51
|
+
|
|
52
|
+
### 4. Run Tests
|
|
53
|
+
```
|
|
54
|
+
# Find test command from package.json scripts or common conventions
|
|
55
|
+
|
|
56
|
+
# Node
|
|
57
|
+
npm test # or npm run test
|
|
58
|
+
|
|
59
|
+
# Rust
|
|
60
|
+
cargo test
|
|
61
|
+
|
|
62
|
+
# Python
|
|
63
|
+
pytest # or python -m pytest
|
|
64
|
+
|
|
65
|
+
# Go
|
|
66
|
+
go test ./...
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
**Pass condition:** All tests pass.
|
|
70
|
+
**Fail:** Record which tests failed and their output.
|
|
71
|
+
|
|
72
|
+
### 5. Run Build (if applicable)
|
|
73
|
+
```
|
|
74
|
+
# Node
|
|
75
|
+
npm run build # or npm run build:prod
|
|
76
|
+
|
|
77
|
+
# Rust
|
|
78
|
+
cargo build
|
|
79
|
+
|
|
80
|
+
# Go
|
|
81
|
+
go build ./...
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
**Pass condition:** Exit code 0, build succeeds.
|
|
85
|
+
|
|
86
|
+
### 6. Output Handoff
|
|
87
|
+
|
|
88
|
+
Write to `.handoffs/dev-flow/verify.md`:
|
|
89
|
+
|
|
90
|
+
```markdown
|
|
91
|
+
# Verification: <title>
|
|
92
|
+
|
|
93
|
+
## Results
|
|
94
|
+
|
|
95
|
+
| Check | Status | Details |
|
|
96
|
+
|-------|--------|---------|
|
|
97
|
+
| Lint | ✅ Pass / ❌ Fail | <details> |
|
|
98
|
+
| Typecheck | ✅ Pass / ❌ Fail / ⏭ Skip | <details> |
|
|
99
|
+
| Tests | ✅ Pass / ❌ Fail | <details> |
|
|
100
|
+
| Build | ✅ Pass / ❌ Fail / ⏭ Skip | <details> |
|
|
101
|
+
|
|
102
|
+
## Overall Verdict
|
|
103
|
+
|
|
104
|
+
**PASS** — All checks passed. Changes are ready.
|
|
105
|
+
|
|
106
|
+
or
|
|
107
|
+
|
|
108
|
+
**NEEDS FIX** — <summary of failures, max 3 bullet points>
|
|
109
|
+
|
|
110
|
+
## Fix Loop Info
|
|
111
|
+
- Attempt: <1/3, 2/3, 3/3>
|
|
112
|
+
- Previous failures: <list>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## Fix Loop
|
|
116
|
+
|
|
117
|
+
If verification fails:
|
|
118
|
+
1. Read `verify.md` to understand failures
|
|
119
|
+
2. Return to Code phase to fix
|
|
120
|
+
3. Re-verify after fixes
|
|
121
|
+
4. Max 3 fix attempts total
|
|
122
|
+
|
|
123
|
+
## Anti-Patterns
|
|
124
|
+
|
|
125
|
+
- ❌ Skipping verification for "trivial" changes
|
|
126
|
+
- ❌ Not running the actual test command (guessing)
|
|
127
|
+
- ❌ Ignoring test failures that seem unrelated
|
|
128
|
+
- ❌ Exceeding max fix loops without asking user
|
|
129
|
+
- ❌ Not detecting the correct project type
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: docs-gen
|
|
3
|
+
description: |
|
|
4
|
+
Generate and update project documentation — README, API docs, code comments, ADRs, and CHANGELOG.
|
|
5
|
+
Detects existing documentation conventions and matches project style.
|
|
6
|
+
Use PROACTIVELY when asked to "document", "write docs", "add comments", "update README", "generate API docs".
|
|
7
|
+
Triggers on: "document", "docs", "readme", "comment", "api docs", "changelog", "adr"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Documentation Generator
|
|
11
|
+
|
|
12
|
+
Analyze code and project structure to generate meaningful, well-structured documentation.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- Adding API documentation for endpoints
|
|
17
|
+
- Generating JSDoc/docstring comments for code
|
|
18
|
+
- Creating or updating README
|
|
19
|
+
- Writing Architecture Decision Records (ADRs)
|
|
20
|
+
- Updating CHANGELOG for a release
|
|
21
|
+
- Documenting configuration, environment variables, or setup steps
|
|
22
|
+
|
|
23
|
+
## Workflow
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
Code/Feature Input → Convention Detection → Doc Type Selection → Generation → Placement
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Step 1: Convention Detection
|
|
30
|
+
|
|
31
|
+
Detect the project's documentation conventions:
|
|
32
|
+
|
|
33
|
+
#### Comment Style
|
|
34
|
+
| Detected | Style | File Clues |
|
|
35
|
+
|----------|-------|------------|
|
|
36
|
+
| JSDoc | `/** @param {string} name */` | `*.ts`, `*.js`, TypeScript project |
|
|
37
|
+
| TSDoc | `/** @param name - description */` | `*.ts`, TypeScript project |
|
|
38
|
+
| Docstring (reST) | `"""Summary.\n:param name:"""` | `*.py`, Sphinx project |
|
|
39
|
+
| Docstring (Google) | `"""Summary.\nArgs:\n name:"""` | `*.py`, Google style |
|
|
40
|
+
| Docstring (NumPy) | `"""Summary.\nParameters\n----------\nname: type"""` | `*.py`, NumPy style |
|
|
41
|
+
| rustdoc | `/// Summary\n/// \n/// # Arguments` | `*.rs` |
|
|
42
|
+
| Godoc | `// Summary` | `*.go` |
|
|
43
|
+
|
|
44
|
+
#### README Style
|
|
45
|
+
Look at existing `README.md` — what sections does it have? What's the tone?
|
|
46
|
+
|
|
47
|
+
#### ADR Format
|
|
48
|
+
Check for `docs/adr/` or `docs/architecture/` directory.
|
|
49
|
+
|
|
50
|
+
#### CHANGELOG Format
|
|
51
|
+
Check for `CHANGELOG.md` — Keep a Changelog? Conventional Commits? Custom?
|
|
52
|
+
|
|
53
|
+
### Step 2: Doc Type Selection
|
|
54
|
+
|
|
55
|
+
| Task | Output | Key Sections |
|
|
56
|
+
|------|--------|-------------|
|
|
57
|
+
| API docs | Endpoint reference | Path, method, request/response schemas, auth, errors |
|
|
58
|
+
| Code comments | Inline annotations | Purpose, params, returns, throws, examples |
|
|
59
|
+
| README | Project README | Title, description, install, usage, API, config, contributing |
|
|
60
|
+
| ADR | ADR file | Context, decision, consequences, alternatives |
|
|
61
|
+
| CHANGELOG | Changelog entry | Added/Changed/Deprecated/Removed/Fixed/Security |
|
|
62
|
+
| Environment docs | `.env.example` | Variable name, description, required/optional, default |
|
|
63
|
+
|
|
64
|
+
### Step 3: Generation
|
|
65
|
+
|
|
66
|
+
#### API Documentation Template
|
|
67
|
+
```markdown
|
|
68
|
+
### `POST /api/users`
|
|
69
|
+
|
|
70
|
+
Create a new user.
|
|
71
|
+
|
|
72
|
+
**Auth:** Requires `admin` role token in `Authorization` header.
|
|
73
|
+
|
|
74
|
+
**Request Body:**
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"name": "string (required)",
|
|
78
|
+
"email": "string (required)",
|
|
79
|
+
"role": "string (optional, default: 'user')"
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
**Response `201`:**
|
|
84
|
+
```json
|
|
85
|
+
{
|
|
86
|
+
"id": "string",
|
|
87
|
+
"name": "string"
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
**Errors:**
|
|
92
|
+
- `400` — Validation error (missing fields, invalid email)
|
|
93
|
+
- `409` — Email already exists
|
|
94
|
+
- `401` — Missing or invalid auth token
|
|
95
|
+
```
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
#### Code Comment Template
|
|
99
|
+
Detected style → generate matching format. Follow existing convention exactly.
|
|
100
|
+
|
|
101
|
+
#### README Template
|
|
102
|
+
```
|
|
103
|
+
# Project Name
|
|
104
|
+
|
|
105
|
+
<one-line description>
|
|
106
|
+
|
|
107
|
+
## Installation
|
|
108
|
+
|
|
109
|
+
<install instructions>
|
|
110
|
+
|
|
111
|
+
## Usage
|
|
112
|
+
|
|
113
|
+
<quick start example>
|
|
114
|
+
|
|
115
|
+
## API
|
|
116
|
+
|
|
117
|
+
<generated from source>
|
|
118
|
+
|
|
119
|
+
## Configuration
|
|
120
|
+
|
|
121
|
+
| Variable | Required | Default | Description |
|
|
122
|
+
|----------|----------|---------|-------------|
|
|
123
|
+
| `PORT` | No | `3000` | Server port |
|
|
124
|
+
|
|
125
|
+
## Development
|
|
126
|
+
|
|
127
|
+
<setup, test, build commands>
|
|
128
|
+
|
|
129
|
+
## Contributing
|
|
130
|
+
|
|
131
|
+
<guidelines or link to CONTRIBUTING.md>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Step 4: Placement
|
|
135
|
+
|
|
136
|
+
- **Code comments:** Added inline, near the documented code
|
|
137
|
+
- **API docs:** `docs/api/` or `README.md` section
|
|
138
|
+
- **README:** Project root `README.md`
|
|
139
|
+
- **ADRs:** `docs/adr/NNNN-title.md` (sequential numbering)
|
|
140
|
+
- **CHANGELOG:** `CHANGELOG.md` (insert at top)
|
|
141
|
+
- **Environment:** `.env.example` at project root
|
|
142
|
+
|
|
143
|
+
## Guiding Principles
|
|
144
|
+
|
|
145
|
+
1. **Document why, not what** — code says what, comments say why
|
|
146
|
+
2. **Keep docs near code** — inline comments > separate docs
|
|
147
|
+
3. **Match existing style** — consistency > personal preference
|
|
148
|
+
4. **Update docs with code** — doc changes in same PR as code changes
|
|
149
|
+
5. **Examples > descriptions** — a code example is worth a paragraph
|
|
150
|
+
|
|
151
|
+
## Anti-Patterns
|
|
152
|
+
|
|
153
|
+
- ❌ Obvious comments (`// increment i` for `i++`)
|
|
154
|
+
- ❌ Outdated documentation (docs that don't match code)
|
|
155
|
+
- ❌ Documenting internal implementation in public API docs
|
|
156
|
+
- ❌ No examples in API documentation
|
|
157
|
+
- ❌ Mixed documentation styles in same project
|
|
158
|
+
|
|
159
|
+
## Related Skills
|
|
160
|
+
|
|
161
|
+
- `pr-review` — Review doc quality alongside code
|
|
162
|
+
- `dev-flow` — Include doc updates in the plan phase
|