5-phase-workflow 1.8.6 → 1.8.8

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.
@@ -0,0 +1,196 @@
1
+ ---
2
+ name: configure-docs-index
3
+ description: Analyzes the codebase, creates project documentation, generates a rebuildable codebase index, and updates CLAUDE.md. Used during /5:implement-feature CONFIGURE.
4
+ allowed-tools: Read, Write, Bash, Glob, Grep
5
+ model: sonnet
6
+ context: fork
7
+ user-invocable: false
8
+ ---
9
+
10
+ # Configure Docs And Index Skill
11
+
12
+ ## Overview
13
+
14
+ This skill handles the documentation and indexing work during Phase 3 (implement-feature) for the CONFIGURE feature. It is called by step-executor to create the project docs, codebase index, and `CLAUDE.md`.
15
+
16
+ It handles one task:
17
+
18
+ - **Analyze Codebase and Create/Update Documentation + Index** - Maps codebase, writes `.5/*.md`, generates `.5/index/*`, and updates `CLAUDE.md`
19
+
20
+ Note: config.json is written directly by `/5:configure` during the Q&A phase.
21
+
22
+ ---
23
+
24
+ ## Modes
25
+
26
+ This skill supports two modes. The analysis (A1), template filling (A2-A3), index generation (A3.5), and CLAUDE.md update (A4-A5) logic is the same in both modes — only the **input source** changes.
27
+
28
+ ### Full Mode (default)
29
+
30
+ Used by `/5:configure` → `/5:implement-feature CONFIGURE` flow.
31
+
32
+ - **Input:** Pattern/command selections from feature spec (`.5/features/CONFIGURE/feature.md`)
33
+ - **Behavior:** Creates documentation, index files, and `CLAUDE.md` from scratch based on feature spec requirements
34
+
35
+ ### Refresh Mode
36
+
37
+ Used by `/5:reconfigure` for lightweight refresh.
38
+
39
+ - **Input:** The Task prompt tells it to refresh documentation and the codebase index
40
+ - **Behavior:** Re-analyzes codebase and overwrites docs, index files, and `CLAUDE.md`
41
+ - **Trigger:** Task prompt includes "REFRESH MODE"
42
+
43
+ In both modes, the analysis and generation logic is identical.
44
+
45
+ ---
46
+
47
+ ## A. Analyze Codebase and Create/Update CLAUDE.md
48
+
49
+ **Process:**
50
+
51
+ ### A1. Codebase Analysis
52
+
53
+ Perform focused analysis to gather data for documentation templates. Only capture information that **cannot be derived** by reading project files directly — skip version numbers, dependency lists, directory layouts, linter configs, and other facts that Claude Code can look up on demand.
54
+
55
+ **Architecture Analysis** (for ARCHITECTURE.md):
56
+ - Identify architectural pattern (MVC, layered, modular, microservices) from directory structure
57
+ - Map layers by directory structure (controllers/, services/, models/, routes/, etc.)
58
+ - Trace data flow patterns (read 2-3 example files from different layers)
59
+ - Identify key abstractions (interfaces, base classes, common patterns)
60
+ - Identify non-obvious conventions: implicit rules not enforced by tooling (e.g., "all services extend BaseService", "barrel exports required per module"). Skip anything in .eslintrc, .prettierrc, tsconfig, etc.
61
+ - Determine where new code should go (new features, tests, utilities)
62
+
63
+ **Testing Analysis** (for TESTING.md):
64
+ - Determine test organization (co-located vs separate `test/` or `spec/`)
65
+ - Identify mocking framework and project-specific mocking conventions
66
+ - Find fixture/factory patterns
67
+ - Note gotchas: setup/teardown quirks, env requirements, flaky areas
68
+
69
+ **Concerns Analysis** (for CONCERNS.md — conditional):
70
+ - Grep for TODO/FIXME/HACK/XXX/DEPRECATED comments across all code
71
+ - Check for common security issues (SQL injection patterns, XSS vulnerabilities)
72
+ - Identify non-obvious integration details: auth flows, required env vars not documented elsewhere, webhook contracts, gotchas with external services
73
+ - Look for performance bottlenecks or scaling limits mentioned in comments/docs
74
+
75
+ ### A2. Fill Templates
76
+
77
+ For each template in `.claude/templates/`:
78
+
79
+ 1. Read template content with Read tool
80
+ 2. Replace placeholders with analyzed data from A1
81
+ 3. **Omit sections entirely if no data was found** — do not write "Not detected" or "None found"
82
+ 4. For CONCERNS.md: if ALL sections would be empty, **do not create the file at all**
83
+
84
+ **Placeholder mapping examples**:
85
+
86
+ ARCHITECTURE.md:
87
+ - `{Pattern name}` → "Layered Architecture" or "MVC" or "Modular Monolith"
88
+ - `{Layer}` → "Controllers", "Services", "Repositories"
89
+ - `{path}` → "src/controllers/", "src/services/"
90
+
91
+ TESTING.md:
92
+ - Describe actual patterns observed, not framework names/versions (those are in config files)
93
+
94
+ CONCERNS.md:
95
+ - `{file paths}` → Actual file paths from grep results
96
+
97
+ ### A3. Write Documentation Files
98
+
99
+ Write filled templates to `.5/` folder:
100
+
101
+ 1. Ensure `.5/` directory exists: `mkdir -p .5`
102
+ 2. Write filled templates:
103
+ - `.5/ARCHITECTURE.md` — always created
104
+ - `.5/TESTING.md` — always created
105
+ - `.5/CONCERNS.md` — **only if concerns were found** (skip if all sections empty)
106
+
107
+ ### A3.5. Generate Codebase Index Script and Index Files
108
+
109
+ Generate a repository-local codebase index that stays generic and works for any language or framework detected in the project.
110
+
111
+ **Requirements:**
112
+ - Create `.5/index/` if it does not exist
113
+ - Generate a script that rebuilds the index at `.5/index/rebuild-index.sh`
114
+ - Make the script self-contained and dependency-light:
115
+ - Prefer portable shell plus standard tools already expected in a dev environment
116
+ - If the project clearly has a better built-in runtime already available (for example Node.js or Python), it is acceptable to generate a small script in that runtime instead, but keep it local to the repo and avoid adding new dependencies
117
+ - The script must inspect the current codebase and write multiple focused Markdown index files into `.5/index/`
118
+ - Include `.5/index/README.md` as a manifest describing what each generated index file contains and how to rebuild the index
119
+ - Group content by concern and adapt to the actual project. Each file should be compact, easy to scan, and optimized for AI/context loading rather than prose documentation.
120
+ - Each generated index file should follow this style:
121
+ - Short title and 1-line purpose statement
122
+ - Bulleted or table-like entries only
123
+ - One entry per route/component/module/model/command as applicable
124
+ - Each entry should include the path and a short descriptor
125
+ - Prefer signatures, exported names, HTTP methods, key fields, and relationships over long explanations
126
+ - Keep entries factual and compact; avoid narrative paragraphs
127
+ - Suggested file shapes:
128
+ - `commands.md` — runnable commands, entrypoints, scripts, key developer workflows
129
+ - `routes.md` — routes, handlers, API endpoints, HTTP methods, notable middleware
130
+ - `modules.md` — modules/packages/components/services and what they own
131
+ - `models.md` — schemas, entities, tables, migrations, key relationships
132
+ - `libraries.md` — shared utilities, helpers, exported functions/classes
133
+ - Suggested categories to create when applicable:
134
+ - Entrypoints / runnable commands
135
+ - Routes / handlers / API surface
136
+ - Components / modules / packages
137
+ - Data models / schemas / migrations
138
+ - Libraries / utilities / shared code
139
+ - Skip categories that do not apply. Do not generate empty placeholder files.
140
+ - The script should overwrite previously generated index files on each run so rebuild is idempotent.
141
+
142
+ ### A4. Create CLAUDE.md
143
+
144
+ Generate CLAUDE.md:
145
+
146
+ CLAUDE.md structure:
147
+ - **Project Overview:** 1-2 sentences from README/package.json
148
+ - **Build & Run Commands:** Build, test, and other detected commands
149
+ - **Workflow Rules:** Include this section verbatim:
150
+ ```
151
+ ## Workflow Rules
152
+ When running `/5:` workflow commands, follow the command instructions exactly as written.
153
+ Do not skip steps, combine phases, or proceed to actions not specified in the current command.
154
+ Each phase produces a specific artifact — do not create artifacts belonging to other phases.
155
+ ```
156
+ - **Coding Guidelines:** The 6 mandatory principles (types, concise docs, short files, extract methods, SRP/DRY, maintainable/modular)
157
+ - **Project Documentation:** Links to whichever `.5/` files were created (only list files that exist)
158
+ - **Codebase Index:** Add a section linking `.5/index/README.md`, the generated index files, and the rebuild script
159
+ - **Index Freshness Rule:** State clearly that if the index files are more than one day old, Claude should regenerate them by running `.5/index/rebuild-index.sh` before relying on them
160
+
161
+ ### A5. Preserve Existing Content
162
+
163
+ If CLAUDE.md already exists:
164
+ - Read current content
165
+ - Identify user-written custom sections (not matching template structure)
166
+ - Preserve under "Custom Documentation" section in new CLAUDE.md
167
+ - Ensure 6 mandatory coding guidelines are retained
168
+
169
+ ---
170
+
171
+ ## Output Contract
172
+
173
+ Returns structured results for each component:
174
+
175
+ ```
176
+ Component A (Documentation + Index): SUCCESS - Created documentation files, codebase index, and CLAUDE.md
177
+ - .5/ARCHITECTURE.md (Pattern: Layered, 4 layers identified)
178
+ - .5/TESTING.md (mocking patterns, gotchas documented)
179
+ - .5/CONCERNS.md (3 TODO items, 1 security note) [or "skipped — no concerns found"]
180
+ - .5/index/rebuild-index.sh (generated index rebuild script)
181
+ - .5/index/*.md (focused codebase index files)
182
+ - CLAUDE.md (updated with references)
183
+ ```
184
+
185
+ Or on failure:
186
+
187
+ ```
188
+ Component A (Documentation + Index): FAILED - Unable to read template files
189
+ ```
190
+
191
+ ## DO NOT
192
+
193
+ - DO NOT overwrite existing user-written CLAUDE.md sections
194
+ - DO NOT include `steps` in config.json
195
+ - DO NOT hardcode conventions - always derive from actual project analysis
196
+ - DO NOT generate empty or placeholder index files
@@ -0,0 +1,314 @@
1
+ ---
2
+ name: configure-skills
3
+ description: Generates project-specific create-*/run-* skills and scoped rules from the current codebase. Used during /5:implement-feature CONFIGURE.
4
+ allowed-tools: Read, Write, Bash, Glob, Grep
5
+ model: sonnet
6
+ context: fork
7
+ user-invocable: false
8
+ ---
9
+
10
+ # Configure Skills Skill
11
+
12
+ ## Overview
13
+
14
+ This skill handles skill and rule generation during Phase 3 (implement-feature) for the CONFIGURE feature. It is called by step-executor to create project-specific skills and scoped rules.
15
+
16
+ It handles two tasks:
17
+
18
+ - **Generate Project-Specific Skills** - Creates SKILL.md files for common project patterns
19
+ - **Generate Scoped Rules** - Creates `.claude/rules/*.md` files with file-type-specific directives
20
+
21
+ Note: config.json is written directly by `/5:configure` during the Q&A phase.
22
+
23
+ ---
24
+
25
+ ## Modes
26
+
27
+ This skill supports two modes. The skill generation and rule generation logic is the same in both modes — only the **input source** changes.
28
+
29
+ ### Full Mode (default)
30
+
31
+ Used by `/5:configure` → `/5:implement-feature CONFIGURE` flow.
32
+
33
+ - **Input:** Pattern/command selections from feature spec (`.5/features/CONFIGURE/feature.md`)
34
+ - **Behavior:** Creates all selected skills and rules from scratch based on feature spec requirements
35
+
36
+ ### Refresh Mode
37
+
38
+ Used by `/5:reconfigure` for lightweight refresh.
39
+
40
+ - **Input:** The Task prompt lists which skills to refresh, create, and remove, and which rules to refresh or remove
41
+ - **Behavior:** Re-analyzes codebase, refreshes/creates/removes skills as specified, and refreshes workflow-generated rules
42
+ - **Trigger:** Task prompt includes "REFRESH MODE"
43
+
44
+ In both modes, the generation logic is identical — only where the requested skill/rule list comes from differs.
45
+
46
+ ---
47
+
48
+ ## A. Generate Project-Specific Skills
49
+
50
+ ### Using skill-creator plugin
51
+
52
+ If `tools.skillCreator.available` is `true` in `.5/config.json`, use the skill-creator plugin's tools (e.g., `create-skill`, `scaffold-skill`) to generate each SKILL.md instead of the template-based approach below. Pass the extracted patterns, conventions, and example file paths as context to the skill-creator tool so it can produce structured, high-quality skill files.
53
+
54
+ If skill-creator is not available, use the existing template-based generation below — no degradation in workflow behavior.
55
+
56
+ **Reads:** Pattern selections from feature spec (`.5/features/CONFIGURE/feature.md`)
57
+
58
+ **Creates:** SKILL.md files in `.claude/skills/{name}/SKILL.md`
59
+
60
+ ### A1. Pattern-Based Skill Generation
61
+
62
+ Skills are determined by what patterns exist in the codebase (detected during `/5:configure`) and what the user selected — not by project type.
63
+
64
+ For EACH pattern selected by the user in the feature spec:
65
+
66
+ 1. **Find examples** - Read 2-3 files from the pattern's location
67
+ 2. **Extract conventions:**
68
+ - File naming (PascalCase, kebab-case, suffix patterns)
69
+ - Directory structure (flat, nested, co-located tests)
70
+ - Import patterns (absolute, relative, aliases)
71
+ - Export patterns (default, named, barrel files)
72
+ - Common boilerplate (decorators, annotations, base classes)
73
+ 3. **Generate SKILL.md** with:
74
+ - Detected conventions as instructions
75
+ - Template derived from actual code
76
+ - Checklist based on common elements found
77
+
78
+ ### A2. Skill Template Structure
79
+
80
+ For each skill, create `.claude/skills/create-{pattern}/SKILL.md`:
81
+
82
+ ```yaml
83
+ ---
84
+ name: create-{pattern}
85
+ description: Creates a {Pattern} following project conventions at {location}.
86
+ allowed-tools: Read, Write, Glob, Grep
87
+ model: haiku
88
+ context: fork
89
+ user-invocable: true
90
+ ---
91
+ ```
92
+
93
+ ```markdown
94
+ # Create {Pattern}
95
+
96
+ ## What This Skill Creates
97
+ A {pattern} following this project's conventions.
98
+
99
+ ## Detected Conventions
100
+ - **Location:** {detected-location}
101
+ - **Naming:** {detected-naming-pattern}
102
+ - **Structure:** {detected-structure}
103
+ - **Imports:** {detected-import-pattern}
104
+
105
+ ## Template
106
+ Based on {example-file}, new {patterns} should follow:
107
+
108
+ \`\`\`{language}
109
+ {template-derived-from-analysis}
110
+ \`\`\`
111
+
112
+ ## Checklist
113
+ - [ ] File created at correct location
114
+ - [ ] Naming convention followed
115
+ - [ ] Required imports added
116
+ - [ ] {pattern-specific-items}
117
+ ```
118
+
119
+ ### A3. Pattern to Skill Name Mapping
120
+
121
+ **Rule:** Skill name is `create-{pattern}` (e.g., `controller` → `create-controller`, `component` → `create-component`, `dto` → `create-dto`). For compound patterns, use the short form: `model/entity` → `create-model`, `api-route` → `create-api-route`.
122
+
123
+ ---
124
+
125
+ ## B. Generate Command Skills (run-*)
126
+
127
+ **Reads:** Command selections from feature spec (`.5/features/CONFIGURE/feature.md`)
128
+
129
+ **Creates:** SKILL.md files in `.claude/skills/run-{command}/SKILL.md`
130
+
131
+ ### B1. Command-Based Skill Generation
132
+
133
+ For EACH command selected by the user in the feature spec:
134
+
135
+ 1. **Read the source** - Check package.json scripts, Makefile, etc.
136
+ 2. **Document the command:**
137
+ - Exact command syntax
138
+ - Available variants (e.g., test:unit, test:e2e)
139
+ - Common flags and options
140
+ - Expected output format
141
+ 3. **Generate SKILL.md** with:
142
+ - Command execution instructions
143
+ - Output parsing guidance
144
+ - Error handling patterns
145
+
146
+ ### B2. Command Skill Template Structure
147
+
148
+ For each skill, create `.claude/skills/run-{command}/SKILL.md`:
149
+
150
+ ```yaml
151
+ ---
152
+ name: run-{command}
153
+ description: Runs {command} for this project using {source}.
154
+ allowed-tools: Bash
155
+ model: haiku
156
+ context: fork
157
+ user-invocable: true
158
+ ---
159
+ ```
160
+
161
+ ```markdown
162
+ # Run {Command}
163
+
164
+ ## What This Skill Does
165
+ Executes the project's {command} command.
166
+
167
+ ## Command
168
+ \`\`\`bash
169
+ {exact-command}
170
+ \`\`\`
171
+
172
+ ## Variants
173
+ {if variants exist}
174
+ - `{variant1}` - {description}
175
+ - `{variant2}` - {description}
176
+
177
+ ## Common Options
178
+ - `--watch` - Run in watch mode (if available)
179
+ - `--coverage` - Generate coverage report (for tests)
180
+ - `--fix` - Auto-fix issues (for lint/format)
181
+
182
+ ## Expected Output
183
+ {describe what success/failure looks like}
184
+
185
+ ## Error Handling
186
+ - If command fails, report the error output
187
+ - Common issues: {list common problems and solutions}
188
+ ```
189
+
190
+ ### B3. Command to Skill Name Mapping
191
+
192
+ **Rule:** Skill name is `run-{category}` (e.g., `build` → `run-build`, `test`/`spec` → `run-tests`, `lint` → `run-lint`). Group variants under the primary category name.
193
+
194
+ ---
195
+
196
+ ## C. Generate Scoped Rules
197
+
198
+ If `rules.generate` is `true` in `.5/config.json`, generate `.claude/rules/` files with project-specific conventions scoped to relevant file types.
199
+
200
+ Rules are **concise directives** (15-40 lines each), not documentation. Documentation lives in `.5/*.md` files. Rules tell Claude what to do when working with specific file types.
201
+
202
+ ### C1. Determine Which Rules to Generate
203
+
204
+ Based on the codebase analysis results, determine which rules apply:
205
+
206
+ | Rule File | Generate When | Source Analysis |
207
+ |-----------|---------------|-----------------|
208
+ | `code-style.md` | Always (if source files exist) | Conventions Analysis |
209
+ | `testing.md` | Test files detected | Testing Analysis |
210
+ | `api-patterns.md` | Controller/route/handler patterns detected | Architecture Analysis |
211
+ | `dependencies.md` | External integrations detected | Integration Analysis |
212
+
213
+ **Skip** any rule whose prerequisite patterns were not detected. Do not generate empty or placeholder rule files.
214
+
215
+ ### C2. Extract Directives and Write Rules
216
+
217
+ For each applicable rule:
218
+
219
+ 1. **Derive `paths:` globs** from detected file locations (e.g., if tests are at `src/**/*.test.ts` and `tests/**/*.spec.ts`, use those patterns)
220
+ 2. **Convert analysis observations into imperative directives** — "Use X", "Always Y", "Never Z"
221
+ 3. **Keep each file 15-40 lines** — be concise and actionable
222
+ 4. **Do not repeat** the 6 mandatory coding guidelines from `CLAUDE.md`
223
+
224
+ Write files to `.claude/rules/`:
225
+
226
+ ```bash
227
+ mkdir -p .claude/rules
228
+ ```
229
+
230
+ ### C3. Rule File Format
231
+
232
+ Each rule file uses YAML frontmatter with `paths:` for scoping. Rules without `paths:` load unconditionally.
233
+
234
+ **Example — `testing.md`:**
235
+
236
+ ```markdown
237
+ ---
238
+ paths:
239
+ - "**/*.test.ts"
240
+ - "**/*.spec.ts"
241
+ ---
242
+
243
+ # Testing Conventions
244
+
245
+ - Use `describe`/`it` blocks with descriptive names
246
+ - Mock external dependencies with jest.mock, never mock internal modules
247
+ - Use factory functions from `tests/factories/` for test data
248
+ - Each test file mirrors its source file path: `src/foo/Bar.ts` → `src/foo/__tests__/Bar.test.ts`
249
+ - Assert one behavior per test
250
+ ```
251
+
252
+ **Example — `code-style.md`:**
253
+
254
+ ```markdown
255
+ ---
256
+ paths:
257
+ - "src/**/*.{ts,tsx}"
258
+ ---
259
+
260
+ # Code Style
261
+
262
+ - Use PascalCase for classes and types, camelCase for functions and variables
263
+ - Import order: external packages → internal modules → relative imports
264
+ - Use absolute imports with `@/` alias
265
+ - Prefer named exports over default exports
266
+ ```
267
+
268
+ **Example — `dependencies.md` (unconditional):**
269
+
270
+ ```markdown
271
+ # Dependency Conventions
272
+
273
+ - Database access through Prisma client only, never raw SQL
274
+ - HTTP requests use axios instance from `src/lib/http.ts`
275
+ - Environment variables accessed via `src/config/env.ts`, never `process.env` directly
276
+ ```
277
+
278
+ ### Refresh Mode Behavior for Rules
279
+
280
+ When running in REFRESH MODE:
281
+ - Re-analyze codebase and overwrite all existing workflow-generated rule files with updated directives
282
+ - Remove rule files for patterns no longer detected in the codebase when instructed by the refresh prompt
283
+ - Create new rule files if new patterns are detected and selected
284
+ - Never modify or remove user-created rules outside the workflow-generated set
285
+
286
+ ---
287
+
288
+ ## Output Contract
289
+
290
+ Returns structured results for each component:
291
+
292
+ ```
293
+ Component B (Pattern Skills): SUCCESS - Generated 3 create-* skills (create-component, create-hook, create-context)
294
+ Component C (Command Skills): SUCCESS - Generated 2 run-* skills (run-tests, run-lint)
295
+ Component D (Rules): SUCCESS - Generated 3 rule files (code-style, testing, dependencies)
296
+ ```
297
+
298
+ Or on failure:
299
+
300
+ ```
301
+ Component B (Pattern Skills): FAILED - No patterns found in codebase
302
+ Component D (Rules): SKIPPED - rules.generate is false in config
303
+ ```
304
+
305
+ ## DO NOT
306
+
307
+ - DO NOT generate skills for patterns that don't exist in the project unless the refresh/configure prompt explicitly told you to create them
308
+ - DO NOT generate command skills for commands that don't exist in the project
309
+ - DO NOT generate rules for patterns not detected in the codebase
310
+ - DO NOT include `steps` in config.json
311
+ - DO NOT hardcode conventions - always derive from actual project analysis
312
+ - DO NOT generate empty or placeholder skill or rule files
313
+ - DO NOT assume command syntax - always read from actual config files (package.json, Makefile, etc.)
314
+ - DO NOT repeat the 6 mandatory coding guidelines from `CLAUDE.md` in rule files
@@ -76,8 +76,7 @@ Check for:
76
76
 
77
77
  Look for patterns in project documentation:
78
78
 
79
- - Check `.5/ARCHITECTURE.md` for architectural patterns (MVC, Clean Architecture, etc.)
80
- - Check `.5/CONVENTIONS.md` for coding conventions and design patterns
79
+ - Check `.5/ARCHITECTURE.md` for architectural patterns and non-obvious conventions
81
80
  - Check `.5/TESTING.md` for test patterns and conventions
82
81
  - Fall back to CLAUDE.md if `.5/` documentation not present
83
82
  - Check module-specific documentation
@@ -1,64 +1,33 @@
1
1
  # Architecture
2
2
 
3
- **Analysis Date:** {YYYY-MM-DD}
3
+ ## Pattern
4
4
 
5
- ## Pattern Overview
5
+ **Overall:** {Pattern name — e.g., Layered, MVC, Modular Monolith}
6
6
 
7
- **Overall:** {Pattern name}
7
+ {1-2 sentences explaining the architectural approach and key design decisions}
8
8
 
9
- **Key Characteristics:**
10
- - {Characteristic 1}
11
- - {Characteristic 2}
12
- - {Characteristic 3}
9
+ ## Layers & Data Flow
13
10
 
14
- ## Layers
15
-
16
- **{Layer Name}:**
17
- - Purpose: {What this layer does}
18
- - Location: `{path}`
19
- - Contains: {Types of code}
20
- - Depends on: {What it uses}
21
- - Used by: {What uses it}
22
-
23
- ## Data Flow
24
-
25
- **{Flow Name}:**
26
-
27
- 1. {Step 1}
28
- 2. {Step 2}
29
- 3. {Step 3}
30
-
31
- **State Management:**
32
- - {How state is handled}
11
+ | Layer | Location | Depends On | Notes |
12
+ |-------|----------|------------|-------|
13
+ | {Layer} | `{path}` | {Dependencies} | {Key responsibility or constraint} |
33
14
 
34
15
  ## Key Abstractions
35
16
 
36
17
  **{Abstraction Name}:**
37
18
  - Purpose: {What it represents}
19
+ - Pattern: {How it's used across the codebase}
38
20
  - Examples: `{file paths}`
39
- - Pattern: {Pattern used}
40
-
41
- ## Entry Points
42
-
43
- **{Entry Point}:**
44
- - Location: `{path}`
45
- - Triggers: {What invokes it}
46
- - Responsibilities: {What it does}
47
-
48
- ## Error Handling
49
-
50
- **Strategy:** {Approach}
51
21
 
52
- **Patterns:**
53
- - {Pattern 1}
54
- - {Pattern 2}
22
+ ## Non-Obvious Conventions
55
23
 
56
- ## Cross-Cutting Concerns
24
+ {ONLY conventions not enforced by tooling or visible in config files. Skip anything in .eslintrc, .prettierrc, tsconfig, etc.}
57
25
 
58
- **Logging:** {Approach}
59
- **Validation:** {Approach}
60
- **Authentication:** {Approach}
26
+ - {e.g., "All services must extend BaseService for lifecycle hooks"}
27
+ - {e.g., "Barrel exports required in each module directory"}
61
28
 
62
- ---
29
+ ## Where to Add New Code
63
30
 
64
- *Architecture analysis: {date}*
31
+ - New feature: `{path}`
32
+ - New tests: `{path}`
33
+ - Shared utilities: `{path}`
@@ -1,6 +1,4 @@
1
- # Codebase Concerns
2
-
3
- **Analysis Date:** {YYYY-MM-DD}
1
+ # Concerns
4
2
 
5
3
  ## Tech Debt
6
4
 
@@ -8,68 +6,28 @@
8
6
  - Issue: {What's the shortcut/workaround}
9
7
  - Files: `{file paths}`
10
8
  - Impact: {What breaks or degrades}
11
- - Fix approach: {How to address it}
12
9
 
13
- ## Known Bugs
10
+ ## Known Issues
14
11
 
15
- **{Bug description}:**
12
+ **{Issue description}:**
16
13
  - Symptoms: {What happens}
17
14
  - Files: `{file paths}`
18
- - Trigger: {How to reproduce}
19
- - Workaround: {If any}
15
+ - Trigger/Workaround: {How to reproduce, how to avoid}
20
16
 
21
- ## Security Considerations
17
+ ## Security Notes
22
18
 
23
19
  **{Area}:**
24
20
  - Risk: {What could go wrong}
25
- - Files: `{file paths}`
26
21
  - Current mitigation: {What's in place}
27
- - Recommendations: {What should be added}
28
-
29
- ## Performance Bottlenecks
30
-
31
- **{Slow operation}:**
32
- - Problem: {What's slow}
33
- - Files: `{file paths}`
34
- - Cause: {Why it's slow}
35
- - Improvement path: {How to speed up}
36
-
37
- ## Fragile Areas
38
-
39
- **{Component/Module}:**
40
- - Files: `{file paths}`
41
- - Why fragile: {What makes it break easily}
42
- - Safe modification: {How to change safely}
43
- - Test coverage: {Gaps}
44
-
45
- ## Scaling Limits
46
-
47
- **{Resource/System}:**
48
- - Current capacity: {Numbers}
49
- - Limit: {Where it breaks}
50
- - Scaling path: {How to increase}
51
-
52
- ## Dependencies at Risk
53
22
 
54
- **{Package}:**
55
- - Risk: {What's wrong}
56
- - Impact: {What breaks}
57
- - Migration plan: {Alternative}
23
+ ## Integration Notes
58
24
 
59
- ## Missing Critical Features
25
+ **{Service/System}:**
26
+ - {Non-obvious details: auth flows, required env vars, webhook contracts, gotchas with external services}
60
27
 
61
- **{Feature gap}:**
62
- - Problem: {What's missing}
63
- - Blocks: {What can't be done}
28
+ ## Performance Notes
64
29
 
65
- ## Test Coverage Gaps
66
-
67
- **{Untested area}:**
68
- - What's not tested: {Specific functionality}
30
+ **{Slow operation or scaling limit}:**
31
+ - Problem: {What's slow or where it breaks}
69
32
  - Files: `{file paths}`
70
- - Risk: {What could break unnoticed}
71
- - Priority: {High/Medium/Low}
72
-
73
- ---
74
-
75
- *Concerns audit: {date}*
33
+ - Improvement path: {How to address}