olympus-ai 4.5.8 → 4.5.9

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 (12) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/dist/installer/index.d.ts +1 -1
  3. package/dist/installer/index.js +1 -1
  4. package/package.json +1 -1
  5. package/resources/rules/core-workflow.md +196 -174
  6. package/resources/rules/inception/application-design.md +1 -1
  7. package/resources/rules/inception/units-generation.md +5 -4
  8. package/resources/rules/inception/workflow-planning.md +3 -3
  9. package/resources/skills/continue/SKILL.md +1 -1
  10. package/resources/skills/plan/SKILL.md +5 -4
  11. package/resources/templates/inception/unit-brief-template.md +5 -5
  12. package/resources/templates/inception/units-template.md +1 -1
package/.claude-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "olympus-ai",
3
- "version": "4.5.8",
3
+ "version": "4.5.9",
4
4
  "description": "Olympus: Multi-agent orchestration for Claude Code. Summon the gods of code.",
5
5
  "author": {
6
6
  "name": "mikev10",
package/dist/installer/index.d.ts CHANGED
@@ -24,7 +24,7 @@ export declare const HOOKS_DIR: string;
24
24
  export declare const SETTINGS_FILE: string;
25
25
  export declare const VERSION_FILE: string;
26
26
  /** Current version - MUST match package.json */
27
- export declare const VERSION = "4.5.8";
27
+ export declare const VERSION = "4.5.9";
28
28
  /** Installation result */
29
29
  export interface InstallResult {
30
30
  success: boolean;
package/dist/installer/index.js CHANGED
@@ -40,7 +40,7 @@ export const HOOKS_DIR = join(CLAUDE_CONFIG_DIR, 'hooks');
40
40
  export const SETTINGS_FILE = join(CLAUDE_CONFIG_DIR, 'settings.json');
41
41
  export const VERSION_FILE = join(CLAUDE_CONFIG_DIR, '.olympus-version.json');
42
42
  /** Current version - MUST match package.json */
43
- export const VERSION = '4.5.8';
43
+ export const VERSION = '4.5.9';
44
44
  /**
45
45
  * Read a content file from the resources/ directory.
46
46
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "olympus-ai",
3
- "version": "4.5.8",
3
+ "version": "4.5.9",
4
4
  "description": "Olympus: Multi-agent orchestration for Claude Code. Summon the gods of code.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
package/resources/rules/core-workflow.md CHANGED
@@ -1,174 +1,196 @@
1
- # AI-DLC Core Workflow (Olympus Reference)
2
-
3
- This document adapts the AWS AI-DLC workflow for Olympus conventions.
4
- Actual workflow execution is driven by the `/plan` command and Olympus agent delegation.
5
-
6
- ## Adaptive Workflow Principle
7
-
8
- **The workflow adapts to the work, not the other way around.**
9
-
10
- The AI model intelligently assesses what stages are needed based on:
11
- 1. User's stated intent and clarity
12
- 2. Existing codebase state (if any)
13
- 3. Complexity and scope of change
14
- 4. Risk and impact assessment
15
-
16
- ## MANDATORY: Rule Details Loading
17
-
18
- **CRITICAL**: When performing any phase, you MUST read and use relevant content from rule detail files installed at `~/.claude/olympus/rules/`.
19
-
20
- **Common Rules**: ALWAYS load common rules at workflow start:
21
- - Load `~/.claude/olympus/rules/common/process-overview.md` for workflow overview
22
- - Load `~/.claude/olympus/rules/common/session-continuity.md` for session resumption guidance
23
- - Load `~/.claude/olympus/rules/common/content-validation.md` for content validation requirements
24
- - Load `~/.claude/olympus/rules/common/markdown-formatting.md` for markdown formatting and markdownlint compliance
25
- - Load `~/.claude/olympus/rules/common/question-format-guide.md` for question formatting rules
26
- - Load `~/.claude/olympus/rules/common/terminology.md` for phase/stage naming conventions
27
- - Load `~/.claude/olympus/rules/common/error-handling.md` for error recovery procedures
28
-
29
- ## MANDATORY: Content Validation
30
-
31
- Before creating ANY file, validate content per `~/.claude/olympus/rules/common/content-validation.md`:
32
- Mermaid syntax, ASCII diagrams, special character escaping, text alternatives.
33
-
34
- ## MANDATORY: Question File Format
35
-
36
- Follow `~/.claude/olympus/rules/common/question-format-guide.md` for multiple choice format, [Answer]: tags, and validation.
37
-
38
- ## MANDATORY: Custom Welcome Message
39
-
40
- At workflow start, load and display `~/.claude/olympus/rules/common/welcome-message.md` once.
41
-
42
- ---
43
-
44
- # INCEPTION PHASE — Determine WHAT to build and WHY
45
-
46
- Each stage: load its rule file BEFORE executing, log all interactions in audit.md, wait for explicit user approval before proceeding (do not auto-advance).
47
-
48
- | Stage | Condition | Rule File |
49
- |-------|-----------|-----------|
50
- | Workspace Detection | ALWAYS | `~/.claude/olympus/rules/inception/workspace-detection.md` |
51
- | Reverse Engineering | Brownfield only (no prior artifacts) | `~/.claude/olympus/rules/inception/reverse-engineering.md` |
52
- | Requirements Analysis | ALWAYS (adaptive depth) | `~/.claude/olympus/rules/inception/requirements-analysis.md` |
53
- | User Stories | Conditional (new user-facing features, multiple personas, complex requirements) | `~/.claude/olympus/rules/inception/user-stories.md` |
54
- | Workflow Planning | ALWAYS | `~/.claude/olympus/rules/inception/workflow-planning.md` |
55
- | Application Design | Conditional (new components/services needed) | `~/.claude/olympus/rules/inception/application-design.md` |
56
- | Units Generation | Conditional (multiple units of work needed) | `~/.claude/olympus/rules/inception/units-generation.md` |
57
-
58
- ---
59
-
60
- # CONSTRUCTION PHASE — Determine HOW to build it
61
-
62
- Each unit is completed fully (design + code) before moving to the next unit. Construction stages use standardized 2-option completion messages (Request Changes / Continue) — NO emergent 3-option behavior.
63
-
64
- **Per-Unit Loop** (for each unit of work):
65
-
66
- | Stage | Condition | Rule File |
67
- |-------|-----------|-----------|
68
- | Functional Design | Conditional (new data models, complex business logic) | `~/.claude/olympus/rules/construction/functional-design.md` |
69
- | NFR Requirements | Conditional (performance, security, scalability, tech stack) | `~/.claude/olympus/rules/construction/nfr-requirements.md` |
70
- | NFR Design | Conditional (NFR Requirements was executed) | `~/.claude/olympus/rules/construction/nfr-design.md` |
71
- | Infrastructure Design | Conditional (infra services, deployment arch) | `~/.claude/olympus/rules/construction/infrastructure-design.md` |
72
- | Code Generation | ALWAYS (two-part: plan then generate) | `~/.claude/olympus/rules/construction/code-generation.md` |
73
-
74
- **Build and Test** (ALWAYS, after all units): Load `~/.claude/olympus/rules/construction/build-and-test.md`
75
-
76
- **Documentation** (ALWAYS, after Build and Test): Load `~/.claude/olympus/rules/construction/documentation.md`
77
-
78
- ---
79
-
80
- # OPERATIONS PHASE — Placeholder for future deployment/monitoring workflows
81
-
82
- ---
83
-
84
- ## Key Principles
85
-
86
- - **Adaptive Execution**: Only execute stages that add value
87
- - **User Control**: User can request stage inclusion/exclusion
88
- - **Progress Tracking**: Update aidlc-state.md with executed and skipped stages
89
- - **Complete Audit Trail**: Log ALL user inputs and AI responses in audit.md with timestamps
90
- - Capture user's COMPLETE RAW INPUT exactly as provided (never summarize)
91
- - Log every interaction, not just approvals
92
- - **Content Validation**: Validate before file creation per content-validation.md rules
93
- - **NO EMERGENT BEHAVIOR**: Construction phases use standardized 2-option completion messages only
94
-
95
- ## MANDATORY: Plan-Level Checkbox Enforcement
96
-
97
- 1. NEVER complete any work without updating plan checkboxes
98
- 2. IMMEDIATELY mark steps `[x]` in the SAME interaction where work is completed
99
- 3. Two-Level tracking: Plan-Level (detailed steps) + Stage-Level (aidlc-state.md)
100
-
101
- ## Prompts Logging Requirements
102
-
103
- - Log EVERY user input with ISO 8601 timestamp in audit.md
104
- - Capture COMPLETE RAW INPUT exactly as provided (never summarize)
105
- - ALWAYS append/edit audit.md — NEVER overwrite
106
-
107
- ### Audit Log Format:
108
- ```markdown
109
- ## [Stage Name]
110
- **Timestamp**: [ISO timestamp]
111
- **User Input**: "[Complete raw user input]"
112
- **AI Response**: "[Action taken]"
113
- **Context**: [Stage/decision]
114
-
115
- ---
116
- ```
117
-
118
- ## Directory Structure
119
-
120
- ```text
121
- <WORKSPACE-ROOT>/ # APPLICATION CODE HERE
122
- ├── [project-specific structure]
123
- ├── aidlc-docs/ # DOCUMENTATION ONLY
124
- │ ├── inception/
125
- │ │ ├── plans/
126
- │ │ ├── reverse-engineering/ # Brownfield only
127
- │ │ ├── requirements/
128
- │ │ ├── user-stories/
129
- │ │ ├── application-design/
130
- │ │ └── units/
131
- │ ├── construction/
132
- │ │ ├── plans/
133
- │ │ ├── {unit-name}/
134
- │ │ │ ├── functional-design/
135
- │ │ │ ├── nfr-requirements/
136
- │ │ │ ├── nfr-design/
137
- │ │ │ ├── infrastructure-design/
138
- │ │ │ └── code/ # Markdown summaries only
139
- │ │ ├── build-and-test/
140
- │ │ └── documentation/
141
- │ ├── operations/ # Placeholder
142
- │ ├── aidlc-state.md
143
- │ └── audit.md
144
- ```
145
-
146
- Application code: workspace root (NEVER in aidlc-docs/). Documentation: aidlc-docs/ only.
147
-
148
- ## Olympus Agent Delegation
149
-
150
- | Stage | Agent | Purpose |
151
- |-------|-------|---------|
152
- | Discovery/Reverse Engineering | `explore-medium` | Codebase analysis |
153
- | Intent/Requirements | `prometheus` | Strategic planning with interview |
154
- | User Stories | `oracle-medium` | Story and persona generation |
155
- | Application Design | `oracle` | Architecture decisions |
156
- | Functional/NFR/Infrastructure Design | `oracle-medium` | Design decisions |
157
- | Code Generation (backend) | `olympian` or `olympian-high` | Implementation |
158
- | Code Generation (frontend) | `frontend-engineer` or `frontend-engineer-high` | UI implementation |
159
- | Build & Test | `qa-tester` | Testing and verification |
160
- | Documentation | `document-writer` | Documentation draft generation |
161
- | Review | `momus` | Critical evaluation |
162
-
163
- ## Skill Stacking for AI-DLC
164
-
165
- | Combination | Effect |
166
- |-------------|--------|
167
- | `/plan` alone | Structured workflow with agent delegation |
168
- | `/plan` + `/ascent` | Adds persistence — cannot stop until all units complete |
169
- | `/plan` + `/ultrawork` | Adds parallel execution and verification guarantees |
170
- | `/plan` + `/ascent` + `/ultrawork` | Full power: parallel, persistent, verified |
171
-
172
- ## Extensions
173
-
174
- Custom extensions in `.aidlc-rule-details/extensions/` at workspace root take precedence over standard rules.
1
+ # AI-DLC Core Workflow (Olympus Reference)
2
+
3
+ This document adapts the AWS AI-DLC workflow for Olympus conventions.
4
+ Actual workflow execution is driven by the `/plan` command and Olympus agent delegation.
5
+
6
+ ## Adaptive Workflow Principle
7
+
8
+ **The workflow adapts to the work, not the other way around.**
9
+
10
+ The AI model intelligently assesses what stages are needed based on:
11
+ 1. User's stated intent and clarity
12
+ 2. Existing codebase state (if any)
13
+ 3. Complexity and scope of change
14
+ 4. Risk and impact assessment
15
+
16
+ ## MANDATORY: Rule Details Loading
17
+
18
+ **CRITICAL**: When performing any phase, you MUST read and use relevant content from rule detail files installed at `~/.claude/olympus/rules/`.
19
+
20
+ **Common Rules**: ALWAYS load common rules at workflow start:
21
+ - Load `~/.claude/olympus/rules/common/process-overview.md` for workflow overview
22
+ - Load `~/.claude/olympus/rules/common/session-continuity.md` for session resumption guidance
23
+ - Load `~/.claude/olympus/rules/common/content-validation.md` for content validation requirements
24
+ - Load `~/.claude/olympus/rules/common/markdown-formatting.md` for markdown formatting and markdownlint compliance
25
+ - Load `~/.claude/olympus/rules/common/question-format-guide.md` for question formatting rules
26
+ - Load `~/.claude/olympus/rules/common/terminology.md` for phase/stage naming conventions
27
+ - Load `~/.claude/olympus/rules/common/error-handling.md` for error recovery procedures
28
+
29
+ ## MANDATORY: Content Validation
30
+
31
+ Before creating ANY file, validate content per `~/.claude/olympus/rules/common/content-validation.md`:
32
+ Mermaid syntax, ASCII diagrams, special character escaping, text alternatives.
33
+
34
+ ## MANDATORY: Question File Format
35
+
36
+ Follow `~/.claude/olympus/rules/common/question-format-guide.md` for multiple choice format, [Answer]: tags, and validation.
37
+
38
+ ## MANDATORY: Custom Welcome Message
39
+
40
+ At workflow start, load and display `~/.claude/olympus/rules/common/welcome-message.md` once.
41
+
42
+ ---
43
+
44
+ # INCEPTION PHASE — Determine WHAT to build and WHY
45
+
46
+ Core decomposition flow: **Intent -> Units -> Stories -> Bolts -> Done**
47
+
48
+ Each stage: load its rule file BEFORE executing, log all interactions in audit.md, wait for explicit user approval before proceeding (do not auto-advance).
49
+
50
+ | Stage | Condition | Rule File |
51
+ |-------|-----------|-----------|
52
+ | Workspace Detection | ALWAYS | `~/.claude/olympus/rules/inception/workspace-detection.md` |
53
+ | Reverse Engineering | Brownfield only (no prior artifacts) | `~/.claude/olympus/rules/inception/reverse-engineering.md` |
54
+ | Requirements Analysis | ALWAYS (adaptive depth) | `~/.claude/olympus/rules/inception/requirements-analysis.md` |
55
+ | Workflow Planning | ALWAYS | `~/.claude/olympus/rules/inception/workflow-planning.md` |
56
+ | Units Generation | Conditional (decomposes intent into independent domain units; includes domain analysis — subsumes former Application Design stage) | `~/.claude/olympus/rules/inception/units-generation.md` |
57
+ | User Stories | Conditional (creates stories per-unit from each unit's assigned requirements; falls back to requirements-based when units skipped) | `~/.claude/olympus/rules/inception/user-stories.md` |
58
+ | Bolt Planning | Conditional (decomposes each unit's stories into executable bolts with dependency tracking) | `~/.claude/olympus/rules/inception/bolt-planning.md` |
59
+
60
+ ---
61
+
62
+ # CONSTRUCTION PHASE — Determine HOW to build it
63
+
64
+ Each unit is completed fully (design + code) before moving to the next unit. Construction stages use standardized 2-option completion messages (Request Changes / Continue) — NO emergent 3-option behavior.
65
+
66
+ **Per-Unit Loop** (for each unit of work):
67
+
68
+ | Stage | Condition | Rule File |
69
+ |-------|-----------|-----------|
70
+ | Functional Design | Conditional (new data models, complex business logic) | `~/.claude/olympus/rules/construction/functional-design.md` |
71
+ | NFR Requirements | Conditional (performance, security, scalability, tech stack) | `~/.claude/olympus/rules/construction/nfr-requirements.md` |
72
+ | NFR Design | Conditional (NFR Requirements was executed) | `~/.claude/olympus/rules/construction/nfr-design.md` |
73
+ | Infrastructure Design | Conditional (infra services, deployment arch) | `~/.claude/olympus/rules/construction/infrastructure-design.md` |
74
+ | Code Generation | ALWAYS (two-part: plan then generate) | `~/.claude/olympus/rules/construction/code-generation.md` |
75
+
76
+ **Build and Test** (ALWAYS, after all units): Load `~/.claude/olympus/rules/construction/build-and-test.md`
77
+
78
+ **Documentation** (ALWAYS, after Build and Test): Load `~/.claude/olympus/rules/construction/documentation.md`
79
+
80
+ ---
81
+
82
+ # OPERATIONS PHASE — Placeholder for future deployment/monitoring workflows
83
+
84
+ ---
85
+
86
+ ## Key Principles
87
+
88
+ - **Adaptive Execution**: Only execute stages that add value
89
+ - **User Control**: User can request stage inclusion/exclusion
90
+ - **Progress Tracking**: Update aidlc-state.md with executed and skipped stages
91
+ - **Complete Audit Trail**: Log ALL user inputs and AI responses in audit.md with timestamps
92
+ - Capture user's COMPLETE RAW INPUT exactly as provided (never summarize)
93
+ - Log every interaction, not just approvals
94
+ - **Content Validation**: Validate before file creation per content-validation.md rules
95
+ - **NO EMERGENT BEHAVIOR**: Construction phases use standardized 2-option completion messages only
96
+
97
+ ## MANDATORY: Plan-Level Checkbox Enforcement
98
+
99
+ 1. NEVER complete any work without updating plan checkboxes
100
+ 2. IMMEDIATELY mark steps `[x]` in the SAME interaction where work is completed
101
+ 3. Two-Level tracking: Plan-Level (detailed steps) + Stage-Level (aidlc-state.md)
102
+
103
+ ## Prompts Logging Requirements
104
+
105
+ - Log EVERY user input with ISO 8601 timestamp in audit.md
106
+ - Capture COMPLETE RAW INPUT exactly as provided (never summarize)
107
+ - ALWAYS append/edit audit.md — NEVER overwrite
108
+
109
+ ### Audit Log Format:
110
+ ```markdown
111
+ ## [Stage Name]
112
+ **Timestamp**: [ISO timestamp]
113
+ **User Input**: "[Complete raw user input]"
114
+ **AI Response**: "[Action taken]"
115
+ **Context**: [Stage/decision]
116
+
117
+ ---
118
+ ```
119
+
120
+ ## Directory Structure
121
+
122
+ ```text
123
+ <WORKSPACE-ROOT>/ # APPLICATION CODE HERE
124
+ ├── [project-specific structure]
125
+ ├── aidlc-docs/ # DOCUMENTATION ONLY
126
+ │ ├── inception/
127
+ │ │ ├── plans/
128
+ │ │ ├── reverse-engineering/ # Brownfield only
129
+ │ │ ├── requirements/
130
+ │ │ ├── units/
131
+ │ │ │ └── {UNIT-NNN-slug}/
132
+ │ │ │ ├── unit-brief.md
133
+ │ │ │ └── stories/ # Per-unit stories (created during User Stories stage)
134
+ │ │ │ ├── S-001-{slug}.md
135
+ │ │ │ └── S-002-{slug}.md
136
+ │ │ └── user-stories/
137
+ │ │ └── personas.md # Project-wide personas (not per-unit)
138
+ │ ├── construction/
139
+ │ │ ├── {UNIT-NNN-slug}/
140
+ │ │ │ ├── functional-design/
141
+ │ │ │ ├── nfr-requirements/
142
+ │ │ │ ├── nfr-design/
143
+ │ │ │ ├── infrastructure-design/
144
+ │ │ │ ├── code/ # Markdown summaries only
145
+ │ │ │ └── bolts/ # Per-unit bolt specs (created during Bolt Planning)
146
+ │ │ │ └── BOLT-NNN-{slug}/
147
+ │ │ │ ├── spec.md
148
+ │ │ │ └── review.md
149
+ │ │ ├── design/
150
+ │ │ ├── build-and-test/
151
+ │ │ └── documentation/
152
+ │ ├── operations/ # Placeholder
153
+ │ ├── aidlc-state.md
154
+ │ └── audit.md
155
+ ```
156
+
157
+ Application code: workspace root (NEVER in aidlc-docs/). Documentation: aidlc-docs/ only.
158
+
159
+ ## Canonical Templates
160
+
161
+ Agents MUST read and follow these template files when creating artifacts:
162
+
163
+ | Template | Path | Used By |
164
+ |----------|------|---------|
165
+ | Units overview | `resources/templates/inception/units-template.md` | Units Generation |
166
+ | Unit brief | `resources/templates/inception/unit-brief-template.md` | Units Generation |
167
+ | Bolt spec | `resources/templates/construction/bolt-spec-template.md` | Bolt Planning |
168
+
169
+ ## Olympus Agent Delegation
170
+
171
+ | Stage | Agent | Purpose |
172
+ |-------|-------|---------|
173
+ | Discovery/Reverse Engineering | `explore-medium` | Codebase analysis |
174
+ | Intent/Requirements | `prometheus` | Strategic planning with interview |
175
+ | Units Generation | `olympian` + `momus` (optional) | Domain decomposition with optional review |
176
+ | User Stories | `oracle-medium` | Per-unit story and persona generation |
177
+ | Bolt Planning | `olympian` + `momus` (optional) | Bolt decomposition with optional review |
178
+ | Functional/NFR/Infrastructure Design | `oracle-medium` | Design decisions |
179
+ | Code Generation (backend) | `olympian` or `olympian-high` | Implementation |
180
+ | Code Generation (frontend) | `frontend-engineer` or `frontend-engineer-high` | UI implementation |
181
+ | Build & Test | `qa-tester` | Testing and verification |
182
+ | Documentation | `document-writer` | Documentation draft generation |
183
+ | Review | `momus` | Critical evaluation |
184
+
185
+ ## Skill Stacking for AI-DLC
186
+
187
+ | Combination | Effect |
188
+ |-------------|--------|
189
+ | `/plan` alone | Structured workflow with agent delegation |
190
+ | `/plan` + `/ascent` | Adds persistence — cannot stop until all units complete |
191
+ | `/plan` + `/ultrawork` | Adds parallel execution and verification guarantees |
192
+ | `/plan` + `/ascent` + `/ultrawork` | Full power: parallel, persistent, verified |
193
+
194
+ ## Extensions
195
+
196
+ Custom extensions in `.aidlc-rule-details/extensions/` at workspace root take precedence over standard rules.
package/resources/rules/inception/application-design.md CHANGED
@@ -41,7 +41,7 @@ Application Design artifacts are the foundation for all construction work. Desig
41
41
  ## Step-by-Step Execution
42
42
 
43
43
  ### 1. Analyze Context
44
- - Read `aidlc-docs/inception/requirements/requirements.md` and `aidlc-docs/inception/user-stories/stories.md`
44
+ - Read `aidlc-docs/inception/requirements/requirements.md` and per-unit stories at `aidlc-docs/inception/units/{UNIT-NNN-slug}/stories/` (or fallback `aidlc-docs/inception/user-stories/stories.md`)
45
45
  - Identify key business capabilities and functional areas
46
46
  - Determine design scope and complexity
47
47
 
package/resources/rules/inception/units-generation.md CHANGED
@@ -37,7 +37,7 @@ This stage produces the following artifacts in `aidlc-docs/{workflowId}/inceptio
37
37
  |----------|------|-----------|-------------|
38
38
  | Unit overview | `inception/units/unit-of-work.md` | ALWAYS | Unit definitions, requirement mapping, dependency graph |
39
39
  | Dependency matrix | `inception/units/unit-of-work-dependency.md` | When 2+ units | Cross-unit dependency analysis |
40
- | Story map | `inception/units/unit-of-work-story-map.md` | After User Stories stage | Story-to-unit assignment mapping (created during User Stories, not during Units Generation) |
40
+ | Story map | `inception/units/unit-of-work-story-map.md` | After User Stories stage | Cross-unit story reference (created during User Stories stage, not during Units Generation) |
41
41
  | Per-unit briefs | `inception/units/{UNIT-NNN-slug}/unit-brief.md` | When 2+ units | Detailed per-unit brief for Bolt Planning |
42
42
 
43
43
  ### Canonical Templates
@@ -183,12 +183,13 @@ This draft mapping will be refined based on Q&A answers but serves as the baseli
183
183
  **ALWAYS** include these mandatory artifacts in the unit plan (when executing the full stage — if the stage is skipped, the Skip Pathway above handles these):
184
184
  - [ ] Generate `aidlc-docs/inception/units/unit-of-work.md` with unit definitions and responsibilities — following `resources/templates/inception/units-template.md`
185
185
  - [ ] Generate `aidlc-docs/inception/units/unit-of-work-dependency.md` with dependency matrix (when 2+ units)
186
- - [ ] Generate `aidlc-docs/inception/units/unit-of-work-story-map.md` mapping stories to units (when stories exist)
186
+ - [ ] ~~Generate `aidlc-docs/inception/units/unit-of-work-story-map.md`~~ — Created during User Stories stage, not here. Do NOT generate this artifact during Units Generation.
187
187
  - [ ] Generate per-unit briefs in `aidlc-docs/inception/units/{unit-slug}/unit-brief.md` (when 2+ units) — following `resources/templates/inception/unit-brief-template.md`
188
188
  - [ ] **Greenfield only**: Document code organization strategy in `unit-of-work.md` (see code-generation.md for structure patterns)
189
189
  - [ ] Validate unit boundaries and dependencies
190
190
  - [ ] Ensure all requirements are assigned to units (100% coverage)
191
191
  - [ ] Prepare unit briefs with placeholder story sections (populated during User Stories stage)
192
+ - [ ] Create `stories/` subdirectory in each unit folder as a placeholder for per-unit stories created in the User Stories stage
192
193
 
193
194
  ## Step 8: Request User Input
194
195
 
@@ -438,7 +439,7 @@ inception/units/UNIT-002-{slug}/unit-brief.md
438
439
 
439
440
  ```yaml
440
441
  input: Requirements (FR-N IDs), application design (if available from brownfield analysis)
441
- output: unit-of-work.md, unit-of-work-dependency.md, unit-of-work-story-map.md, per-unit briefs
442
+ output: unit-of-work.md, unit-of-work-dependency.md, per-unit briefs (unit-of-work-story-map.md created during User Stories stage)
442
443
  constraints:
443
444
  requirement_coverage: 100% (every FR assigned to a unit)
444
445
  must_requirement_coverage: 100%
@@ -501,4 +502,4 @@ checkpoints: 0 (part of inception review gate)
501
502
 
502
503
  ## Next Stage: User Stories
503
504
 
504
- After units are approved, the workflow proceeds to **User Stories** — a separate inception stage that creates per-unit user stories from each unit's assigned requirements. Stories are scoped to their parent unit and reference the unit ID. After stories are created, the workflow proceeds to **Bolt Planning**, which decomposes each unit's stories into bolt spec files.
505
+ After units are approved, the workflow proceeds to **User Stories** — a separate inception stage that creates per-unit user stories in each unit's `stories/` directory (e.g., `inception/units/{UNIT-NNN-slug}/stories/S-001-{slug}.md`). Stories are scoped to their parent unit and reference the unit ID. Personas remain project-wide at `inception/user-stories/personas.md`. After stories are created, the workflow proceeds to **Bolt Planning**, which decomposes each unit's stories into bolt spec files.
package/resources/rules/inception/workflow-planning.md CHANGED
@@ -23,10 +23,10 @@
23
23
  > **Traceability prerequisite**: Verify that `requirements.md` contains named requirement IDs in `FR-NNN` format (e.g., `FR-001`, `FR-002`). These IDs are referenced throughout construction — bolt specs cite them in `requirements` frontmatter and `## Traceability` sections, and the bolt planner performs coverage checks against `must`-priority requirements. If requirements exist but lack explicit IDs, add them before proceeding to construction.
24
24
 
25
25
  ### 1.3 Load User Stories (if executed)
26
- - stories.md
26
+ - Per-unit stories from `inception/units/{UNIT-NNN-slug}/stories/` (when units exist) or fallback `stories.md`
27
27
  - personas.md
28
28
 
29
- > **Traceability prerequisite**: Verify that `stories.md` contains named story IDs in `S-NNN` format (e.g., `S-001`, `S-002`). These IDs are referenced in bolt specs and coverage validation. If stories exist but lack explicit IDs, add them before proceeding to construction.
29
+ > **Note**: User stories and their `S-NNN` IDs are created during the User Stories stage, which runs after units are defined. If Workflow Planning runs before User Stories, this section will have no artifacts to load. Story IDs (S-NNN) are created during the User Stories stage which runs after units are defined.
30
30
 
31
31
  ## Step 2: Detailed Scope and Impact Analysis
32
32
 
@@ -196,7 +196,7 @@ Evaluate risk level:
196
196
 
197
197
  3. **Conditionally create `unit-of-work-dependency.md`** — ONLY if units have actual blocking dependencies between them. Skip this file when all units are independent or can execute in any order.
198
198
 
199
- 4. **Conditionally create `unit-of-work-story-map.md`** — ONLY if user stories exist AND are not already mapped to units within `stories.md`. Skip this file when story-to-unit mappings are already recorded elsewhere.
199
+ 4. **Conditionally create `unit-of-work-story-map.md`** — Created during the User Stories stage, not during Workflow Planning or Unit Registration. Do NOT create this file here.
200
200
 
201
201
  5. **Update `checkpoint.json`**: Record units in `construction_units` array using the `U-NNN` IDs. Set units-generation status to `"skipped"` with `unit_registration_completed: true`.
202
202
 
package/resources/skills/continue/SKILL.md CHANGED
@@ -90,7 +90,7 @@ Follow the artifact loading rules from `session-continuity.md`. Based on the cur
90
90
  | workflow-planning | inception/intent.md, inception/requirements/requirements.md, inception/requirements/requirements-analysis-questions.md |
91
91
  | units-generation | All above + inception/plans/workflow-routing.md |
92
92
  | user-stories | All above + inception/units/unit-of-work.md, inception/units/{UNIT-NNN-slug}/unit-brief.md (per-unit briefs) |
93
- | bolt-planning | All above + inception/user-stories/stories.md, inception/user-stories/personas.md, inception/units/unit-of-work-story-map.md, construction/{UNIT-NNN}/bolts/ spec.md files (if any exist) |
93
+ | bolt-planning | All above + inception/units/{UNIT-NNN-slug}/stories/ (per-unit story files) or inception/user-stories/stories.md (fallback), inception/user-stories/personas.md, inception/units/unit-of-work-story-map.md, construction/{UNIT-NNN}/bolts/ spec.md files (if any exist) |
94
94
 
95
95
  ### Construction Phase Artifacts
96
96
 
package/resources/skills/plan/SKILL.md CHANGED
@@ -1078,7 +1078,7 @@ Mark `inception_stages["user-stories"].status = "in_progress"`. Update checkpoin
1078
1078
 
1079
1079
  Read `intent.md`, `requirements.md`, and unit artifacts (`inception/units/unit-of-work.md`, per-unit briefs) for context.
1080
1080
 
1081
- When units exist (units-generation has completed), create stories scoped to each unit — reading each unit's assigned requirements from the unit brief and creating stories that reference their parent unit ID. When units do not exist (units-generation was skipped), create stories from requirements.md directly without unit scoping.
1081
+ When units exist (units-generation has completed), create stories scoped to each unit as individual files at `inception/units/{UNIT-NNN-slug}/stories/{S-NNN}-{slug}.md` — reading each unit's assigned requirements from the unit brief and creating stories that reference their parent unit ID. When units do not exist (units-generation was skipped), fall back to creating stories in `inception/user-stories/stories.md` without unit scoping.
1082
1082
 
1083
1083
  **`aidlc-docs/{workflowId}/inception/user-stories/personas.md`**:
1084
1084
 
@@ -1093,7 +1093,7 @@ When units exist (units-generation has completed), create stories scoped to each
1093
1093
  - **Key User Stories**: S-001, S-002, ...
1094
1094
  ```
1095
1095
 
1096
- **`aidlc-docs/{workflowId}/inception/user-stories/stories.md`** (Gherkin format):
1096
+ **`aidlc-docs/{workflowId}/inception/user-stories/stories.md`** (fallback when units skipped — Gherkin format):
1097
1097
 
1098
1098
  ```markdown
1099
1099
  # User Stories: {Title}
@@ -1151,8 +1151,9 @@ After stories are created, if units exist, generate the story-to-unit mapping an
1151
1151
 
1152
1152
  ### Artifacts generated
1153
1153
  - `aidlc-docs/{workflowId}/inception/user-stories/personas.md`
1154
- - `aidlc-docs/{workflowId}/inception/user-stories/stories.md`
1155
- - `aidlc-docs/{workflowId}/inception/units/unit-of-work-story-map.md` (when units exist)
1154
+ - `aidlc-docs/{workflowId}/inception/units/{UNIT-NNN-slug}/stories/` — per-unit story files (when units exist)
1155
+ - `aidlc-docs/{workflowId}/inception/user-stories/stories.md` — flat file (fallback when units skipped)
1156
+ - `aidlc-docs/{workflowId}/inception/units/unit-of-work-story-map.md` (cross-unit story reference, when units exist)
1156
1157
 
1157
1158
  ### What needs your review
1158
1159
  - [ ] Personas accurately represent the intended users
package/resources/templates/inception/unit-brief-template.md CHANGED
@@ -91,12 +91,12 @@ updated: "{YYYY-MM-DDTHH:MM:SSZ}"
91
91
 
92
92
  ### Stories Assigned
93
93
 
94
- > **Note**: This section is initially created with placeholder content during Units Generation. It is populated with actual story data when the User Stories stage runs after units are defined.
94
+ > **Note**: This section is initially created with placeholder content during Units Generation. It is populated with actual story data when the User Stories stage runs after units are defined. Stories for this unit are stored at `inception/units/{UNIT-NNN-slug}/stories/`. Each story is an individual markdown file following the per-unit story template.
95
95
 
96
- | Story ID | Title | Priority | Status |
97
- |----------|-------|----------|--------|
98
- | S-001 | {Title} | Must | Planned |
99
- | S-002 | {Title} | Should | Planned |
96
+ | Story ID | Title | Priority | Status | File |
97
+ |----------|-------|----------|--------|------|
98
+ | S-001 | {Title} | Must | Planned | `stories/S-001-{slug}.md` |
99
+ | S-002 | {Title} | Should | Planned | `stories/S-002-{slug}.md` |
100
100
 
101
101
  ## Dependencies
102
102
 
package/resources/templates/inception/units-template.md CHANGED
@@ -61,7 +61,7 @@ updated: "{YYYY-MM-DDTHH:MM:SSZ}"
61
61
  - **Responsibility**: {Single responsibility description}
62
62
  - **Scope**: {What is IN this unit}
63
63
  - **Assigned Requirements**: FR-1, FR-2
64
- - **Assigned Stories**: S-001, S-002, S-003
64
+ - **Assigned Stories**: S-001, S-002, S-003 (stories will be created at `inception/units/{UNIT-NNN-slug}/stories/` during the User Stories stage)
65
65
  - **Dependencies**: None | {U-NNN: reason}
66
66
  - **Estimated Complexity**: S | M | L | XL
67
67
  - **Estimated Effort**: {hours}