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.
- package/README.md +67 -33
- package/bin/install.js +510 -34
- package/docs/workflow-guide.md +1 -1
- package/package.json +1 -1
- package/src/commands/5/address-review-findings.md +2 -2
- package/src/commands/5/configure.md +39 -27
- package/src/commands/5/eject.md +110 -0
- package/src/commands/5/plan-feature.md +0 -1
- package/src/commands/5/plan-implementation.md +0 -1
- package/src/commands/5/quick-implement.md +0 -1
- package/src/commands/5/reconfigure.md +20 -17
- package/src/commands/5/update.md +16 -3
- package/src/hooks/statusline.js +80 -41
- package/src/skills/configure-docs-index/SKILL.md +196 -0
- package/src/skills/configure-skills/SKILL.md +314 -0
- package/src/skills/generate-readme/SKILL.md +1 -2
- package/src/templates/ARCHITECTURE.md +16 -47
- package/src/templates/CONCERNS.md +12 -54
- package/src/templates/TESTING.md +12 -95
- package/src/skills/build-project/SKILL.md +0 -151
- package/src/skills/configure-project/SKILL.md +0 -465
- package/src/skills/run-tests/SKILL.md +0 -162
- package/src/templates/CONVENTIONS.md +0 -75
- package/src/templates/INTEGRATIONS.md +0 -65
- package/src/templates/STACK.md +0 -60
- package/src/templates/STRUCTURE.md +0 -60
|
@@ -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
|
|
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
|
-
|
|
3
|
+
## Pattern
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Overall:** {Pattern name — e.g., Layered, MVC, Modular Monolith}
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
{1-2 sentences explaining the architectural approach and key design decisions}
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
- {Characteristic 1}
|
|
11
|
-
- {Characteristic 2}
|
|
12
|
-
- {Characteristic 3}
|
|
9
|
+
## Layers & Data Flow
|
|
13
10
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
-
|
|
53
|
-
- {Pattern 1}
|
|
54
|
-
- {Pattern 2}
|
|
22
|
+
## Non-Obvious Conventions
|
|
55
23
|
|
|
56
|
-
|
|
24
|
+
{ONLY conventions not enforced by tooling or visible in config files. Skip anything in .eslintrc, .prettierrc, tsconfig, etc.}
|
|
57
25
|
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
31
|
+
- New feature: `{path}`
|
|
32
|
+
- New tests: `{path}`
|
|
33
|
+
- Shared utilities: `{path}`
|
|
@@ -1,6 +1,4 @@
|
|
|
1
|
-
#
|
|
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
|
|
10
|
+
## Known Issues
|
|
14
11
|
|
|
15
|
-
**{
|
|
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
|
|
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
|
-
|
|
55
|
-
- Risk: {What's wrong}
|
|
56
|
-
- Impact: {What breaks}
|
|
57
|
-
- Migration plan: {Alternative}
|
|
23
|
+
## Integration Notes
|
|
58
24
|
|
|
59
|
-
|
|
25
|
+
**{Service/System}:**
|
|
26
|
+
- {Non-obvious details: auth flows, required env vars, webhook contracts, gotchas with external services}
|
|
60
27
|
|
|
61
|
-
|
|
62
|
-
- Problem: {What's missing}
|
|
63
|
-
- Blocks: {What can't be done}
|
|
28
|
+
## Performance Notes
|
|
64
29
|
|
|
65
|
-
|
|
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
|
-
-
|
|
71
|
-
- Priority: {High/Medium/Low}
|
|
72
|
-
|
|
73
|
-
---
|
|
74
|
-
|
|
75
|
-
*Concerns audit: {date}*
|
|
33
|
+
- Improvement path: {How to address}
|