my-opencode 1.3.4 → 2.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 -21
- package/README.md +299 -270
- package/agents/architect.md +30 -30
- package/agents/backend-dev.md +29 -0
- package/agents/business-analyst.md +30 -0
- package/agents/code-reviewer.md +29 -29
- package/agents/design-evidence.md +29 -0
- package/agents/frontend-dev.md +29 -0
- package/agents/system-designer.md +30 -0
- package/agents/team-lead.md +65 -60
- package/agents/tech-writer.md +30 -30
- package/agents/test-engineer.md +30 -30
- package/agents/verifier.md +38 -33
- package/bin/cli.js +366 -364
- package/bin/moc +198 -198
- package/opencode.json +218 -170
- package/package.json +53 -51
- package/plugins/README.md +67 -67
- package/plugins/provider-profile.mjs +203 -194
- package/scripts/postinstall.js +202 -202
- package/scripts/validate-role-flow.mjs +90 -0
- package/skills/adr/SKILL.md +91 -91
- package/skills/adr/references/templates.md +100 -100
- package/skills/adr/scripts/README.md +5 -5
- package/skills/design-evidence/SKILL.md +56 -0
- package/skills/dev-flow/SKILL.md +126 -188
- package/skills/dev-flow/references/code-phase.md +35 -72
- package/skills/dev-flow/references/contract-phase.md +66 -81
- package/skills/dev-flow/references/verify-phase.md +70 -129
- package/skills/dev-flow/scripts/README.md +3 -3
- package/skills/docs-gen/SKILL.md +162 -162
- package/skills/docs-gen/references/doc-styles.md +216 -216
- package/skills/docs-gen/scripts/README.md +5 -5
- package/skills/orchestrate/SKILL.md +63 -112
- package/skills/orchestrate/references/orchestration-patterns.md +49 -56
- package/skills/pr-review/SKILL.md +110 -110
- package/skills/pr-review/references/review-dimensions.md +117 -117
- package/skills/pr-review/references/security-checklist.md +122 -122
- package/skills/pr-review/scripts/README.md +5 -5
- package/skills/test-gen/SKILL.md +143 -143
- package/skills/test-gen/references/framework-detection.md +105 -105
- package/skills/test-gen/references/test-patterns.md +260 -260
- package/skills/test-gen/scripts/README.md +5 -5
- package/agents/executor.md +0 -30
- package/agents/fullstack-dev.md +0 -57
- package/agents/spec-writer.md +0 -37
|
@@ -1,129 +1,70 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
## Entry Conditions
|
|
4
|
-
|
|
5
|
-
-
|
|
6
|
-
-
|
|
7
|
-
|
|
8
|
-
##
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
|
1
|
+
# QA and Verification Phase
|
|
2
|
+
|
|
3
|
+
## Entry Conditions
|
|
4
|
+
|
|
5
|
+
- Feature artifacts and implementation handoffs exist.
|
|
6
|
+
- Frontend/backend slices have completed review.
|
|
7
|
+
|
|
8
|
+
## Verification Order
|
|
9
|
+
|
|
10
|
+
### 1. Contract Traceability
|
|
11
|
+
|
|
12
|
+
- Read `evidence-pack.md`, `business-requirements.md`, `technical-design.md`, role contracts, and `traceability.md`.
|
|
13
|
+
- Confirm each UI action maps to evidence, business rule, API/data effect, and verification.
|
|
14
|
+
- Mark missing permission, state, source, or error decisions as blockers.
|
|
15
|
+
|
|
16
|
+
### 2. Business
|
|
17
|
+
|
|
18
|
+
Verify use cases, business rules, states, negative paths, duplicate/retry behavior, and acceptance intent.
|
|
19
|
+
|
|
20
|
+
### 3. Visual / Interaction
|
|
21
|
+
|
|
22
|
+
Verify approved design, state inventory, responsive behavior, keyboard/focus behavior, semantic structure, and accessibility.
|
|
23
|
+
|
|
24
|
+
### 4. API / Data
|
|
25
|
+
|
|
26
|
+
Verify request/response/error schemas, persistence, query patterns, pagination, and contract tests.
|
|
27
|
+
|
|
28
|
+
### 5. Security / Operations
|
|
29
|
+
|
|
30
|
+
Verify authorization and scope, audit, performance targets, observability, migration, and rollback.
|
|
31
|
+
|
|
32
|
+
### 6. Mechanical Checks
|
|
33
|
+
|
|
34
|
+
Detect project type and run lint, typecheck, tests, and build. Stop at the first blocking failure and record exact output.
|
|
35
|
+
|
|
36
|
+
## Output
|
|
37
|
+
|
|
38
|
+
Return a structured report to `team-lead`. The orchestrator persists the final report at `docs/specs/<feature>/verification-report.md`:
|
|
39
|
+
|
|
40
|
+
```markdown
|
|
41
|
+
# Verification Report: <feature>
|
|
42
|
+
|
|
43
|
+
## Results
|
|
44
|
+
|
|
45
|
+
| ID | Layer | Status | Evidence |
|
|
46
|
+
|----|-------|--------|----------|
|
|
47
|
+
| VER-001 | Business | Pass / Fail | <details> |
|
|
48
|
+
|
|
49
|
+
## Mechanical Checks
|
|
50
|
+
|
|
51
|
+
| Check | Status | Details |
|
|
52
|
+
|-------|--------|---------|
|
|
53
|
+
| Lint | Pass / Fail / Skip | <details> |
|
|
54
|
+
| Typecheck | Pass / Fail / Skip | <details> |
|
|
55
|
+
| Tests | Pass / Fail / Skip | <details> |
|
|
56
|
+
| Build | Pass / Fail / Skip | <details> |
|
|
57
|
+
|
|
58
|
+
## Overall Verdict
|
|
59
|
+
|
|
60
|
+
PASS or NEEDS FIX
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Fix Loop
|
|
64
|
+
|
|
65
|
+
1. Identify the failing ID and owning layer.
|
|
66
|
+
2. Update the contract if the contract is wrong.
|
|
67
|
+
3. Fix the bounded implementation slice.
|
|
68
|
+
4. Re-run review and verification.
|
|
69
|
+
|
|
70
|
+
Allow at most three attempts before reporting the blocker.
|
|
@@ -1,3 +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).
|
|
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).
|
package/skills/docs-gen/SKILL.md
CHANGED
|
@@ -1,162 +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
|
|
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
|