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.
Files changed (35) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +163 -0
  3. package/agents/architect.md +30 -0
  4. package/agents/code-reviewer.md +29 -0
  5. package/agents/executor.md +30 -0
  6. package/agents/fullstack-dev.md +53 -0
  7. package/agents/spec-writer.md +37 -0
  8. package/agents/team-lead.md +60 -0
  9. package/agents/tech-writer.md +30 -0
  10. package/agents/test-engineer.md +30 -0
  11. package/agents/verifier.md +33 -0
  12. package/bin/cli.js +272 -0
  13. package/opencode.json +164 -0
  14. package/package.json +44 -0
  15. package/skills/adr/SKILL.md +91 -0
  16. package/skills/adr/references/templates.md +100 -0
  17. package/skills/adr/scripts/README.md +5 -0
  18. package/skills/dev-flow/SKILL.md +188 -0
  19. package/skills/dev-flow/references/code-phase.md +72 -0
  20. package/skills/dev-flow/references/contract-phase.md +81 -0
  21. package/skills/dev-flow/references/verify-phase.md +129 -0
  22. package/skills/dev-flow/scripts/README.md +3 -0
  23. package/skills/docs-gen/SKILL.md +162 -0
  24. package/skills/docs-gen/references/doc-styles.md +216 -0
  25. package/skills/docs-gen/scripts/README.md +5 -0
  26. package/skills/orchestrate/SKILL.md +112 -0
  27. package/skills/orchestrate/references/orchestration-patterns.md +56 -0
  28. package/skills/pr-review/SKILL.md +110 -0
  29. package/skills/pr-review/references/review-dimensions.md +117 -0
  30. package/skills/pr-review/references/security-checklist.md +122 -0
  31. package/skills/pr-review/scripts/README.md +5 -0
  32. package/skills/test-gen/SKILL.md +143 -0
  33. package/skills/test-gen/references/framework-detection.md +105 -0
  34. package/skills/test-gen/references/test-patterns.md +260 -0
  35. 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,3 @@
1
+ # dev-flow Scripts
2
+
3
+ Utility scripts for the dev-flow skill. Currently empty — scripts will be added as needed (e.g., handoff management, project type detection).
@@ -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