project-iris 0.0.17 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/README.md +86 -15
  2. package/flows/aidlc/README.md +358 -214
  3. package/flows/aidlc/agents/README.md +154 -0
  4. package/flows/aidlc/agents/master-agent.md +211 -24
  5. package/flows/aidlc/memory-bank.yaml +58 -10
  6. package/flows/aidlc/quick-start.md +7 -7
  7. package/flows/aidlc/skills/README.md +106 -0
  8. package/flows/aidlc/skills/construction/bolt-list.md +16 -0
  9. package/flows/aidlc/skills/construction/bolt-start.md +37 -1
  10. package/flows/aidlc/skills/construction/navigator.md +1 -1
  11. package/flows/aidlc/skills/inception/bolt-plan.md +1 -1
  12. package/flows/aidlc/skills/inception/intent-create.md +91 -2
  13. package/flows/aidlc/skills/inception/requirements.md +105 -6
  14. package/flows/aidlc/skills/master/answer-question.md +1 -1
  15. package/flows/aidlc/skills/master/code-elevate.md +434 -0
  16. package/flows/aidlc/skills/master/explain-flow.md +6 -6
  17. package/flows/aidlc/skills/master/project-init.md +110 -12
  18. package/flows/aidlc/skills/operations/build.md +32 -4
  19. package/flows/aidlc/skills/operations/monitor.md +75 -14
  20. package/flows/aidlc/skills/operations/rollback.md +239 -0
  21. package/flows/aidlc/templates/README.md +128 -0
  22. package/flows/aidlc/templates/construction/bolt-template.md +5 -5
  23. package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/{ddd-02-technical-design-template.md → ddd-02-logical-design-template.md} +1 -1
  24. package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt.md +27 -27
  25. package/flows/aidlc/templates/construction/bolt-types/simple-construction-bolt.md +6 -6
  26. package/flows/aidlc/templates/construction/construction-guide.md +244 -0
  27. package/flows/aidlc/templates/construction/construction-log-template.md +7 -6
  28. package/flows/aidlc/templates/construction/elevation-dynamic-model-template.md +265 -0
  29. package/flows/aidlc/templates/construction/elevation-static-model-template.md +204 -0
  30. package/flows/aidlc/templates/inception/prfaq-template.md +147 -0
  31. package/flows/aidlc/templates/inception/requirements-template.md +70 -5
  32. package/flows/aidlc/templates/inception/risks-template.md +214 -0
  33. package/flows/aidlc/templates/operations/deployment-unit-template.md +228 -0
  34. package/lib/constants.js +13 -9
  35. package/package.json +1 -1
  36. package/flows/aidlc/templates/inception/project/README.md +0 -55
  37. /package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/{ddd-01-domain-model-template.md → ddd-01-domain-design-template.md} +0 -0
@@ -2,6 +2,8 @@
2
2
 
3
3
  Welcome to the **AI-DLC (AI-Driven Development Life Cycle)** flow for iris!
4
4
 
5
+ ---
6
+
5
7
  ## What is AI-DLC?
6
8
 
7
9
  AI-DLC is an **AWS methodology** for AI-native software development that optimizes for how AI agents work best. Unlike traditional methodologies, AI-DLC:
@@ -11,6 +13,112 @@ AI-DLC is an **AWS methodology** for AI-native software development that optimiz
11
13
  - Follows **DDD (Domain-Driven Design)** principles
12
14
  - Maintains **persistent context** across sessions through memory bank
13
15
  - Operates in **three sequential phases**: Inception → Construction → Operations
16
+ - Supports both **greenfield** (new projects) and **brownfield** (existing codebases) scenarios
17
+
18
+ ---
19
+
20
+ ## Directory Structure
21
+
22
+ ```text
23
+ src/flows/aidlc/
24
+ ├── agents/ # Agent definitions (4 agents)
25
+ │ ├── master-agent.md # Orchestrator - routes to appropriate agent
26
+ │ ├── inception-agent.md # Planning phase agent
27
+ │ ├── construction-agent.md # Building phase agent
28
+ │ └── operations-agent.md # Deployment phase agent
29
+
30
+ ├── skills/ # Agent capabilities (27 skills total)
31
+ │ ├── master/ # Master Agent skills (6)
32
+ │ │ ├── project-init.md # Initialize project with standards
33
+ │ │ ├── code-elevate.md # Brownfield code elevation
34
+ │ │ ├── analyze-context.md # Analyze current project state
35
+ │ │ ├── route-request.md # Route to appropriate agent
36
+ │ │ ├── explain-flow.md # Explain AI-DLC methodology
37
+ │ │ └── answer-question.md # Answer user questions
38
+ │ │
39
+ │ ├── inception/ # Inception Agent skills (10)
40
+ │ │ ├── navigator.md # Navigate inception workflow
41
+ │ │ ├── intent-create.md # Create new intent with PRFAQ
42
+ │ │ ├── intent-list.md # List all intents
43
+ │ │ ├── requirements.md # Gather FR/NFR with measurement criteria
44
+ │ │ ├── risks.md # Define and assess risks
45
+ │ │ ├── context.md # Define system context
46
+ │ │ ├── units.md # Decompose into units
47
+ │ │ ├── story-create.md # Create user stories
48
+ │ │ ├── bolt-plan.md # Plan bolts for stories
49
+ │ │ └── review.md # Review inception artifacts
50
+ │ │
51
+ │ ├── construction/ # Construction Agent skills (5)
52
+ │ │ ├── navigator.md # Navigate construction workflow
53
+ │ │ ├── bolt-list.md # List all bolts
54
+ │ │ ├── bolt-start.md # Start/continue bolt execution
55
+ │ │ ├── bolt-status.md # Check bolt progress
56
+ │ │ └── bolt-replan.md # Replan bolts if needed
57
+ │ │
58
+ │ └── operations/ # Operations Agent skills (6)
59
+ │ ├── navigator.md # Navigate operations workflow
60
+ │ ├── build.md # Build deployment artifacts
61
+ │ ├── deploy.md # Deploy to environment
62
+ │ ├── verify.md # Verify deployment
63
+ │ ├── monitor.md # Setup monitoring and SLOs
64
+ │ └── rollback.md # Rollback deployment
65
+
66
+ ├── templates/ # Artifact templates
67
+ │ ├── inception/ # Inception phase templates (9)
68
+ │ │ ├── requirements-template.md # Requirements document
69
+ │ │ ├── prfaq-template.md # Press Release / FAQ
70
+ │ │ ├── risks-template.md # Risk assessment
71
+ │ │ ├── system-context-template.md # System context diagram
72
+ │ │ ├── units-template.md # Unit decomposition overview
73
+ │ │ ├── unit-brief-template.md # Individual unit brief
74
+ │ │ ├── stories-template.md # Stories collection
75
+ │ │ ├── story-template.md # Individual user story
76
+ │ │ └── inception-log-template.md # Inception progress log
77
+ │ │
78
+ │ ├── construction/ # Construction phase templates
79
+ │ │ ├── bolt-template.md # Bolt instance metadata
80
+ │ │ ├── construction-guide.md # Construction workflow guide
81
+ │ │ ├── construction-log-template.md # Construction progress log
82
+ │ │ ├── elevation-static-model-template.md # Brownfield static model
83
+ │ │ ├── elevation-dynamic-model-template.md # Brownfield dynamic model
84
+ │ │ │
85
+ │ │ ├── bolt-types/ # Bolt type definitions (3 types)
86
+ │ │ │ ├── ddd-construction-bolt.md # DDD bolt (5 stages)
87
+ │ │ │ ├── simple-construction-bolt.md # Simple bolt (3 stages)
88
+ │ │ │ ├── spike-bolt.md # Research/exploration bolt
89
+ │ │ │ └── ddd-construction-bolt/ # DDD stage templates
90
+ │ │ │ ├── ddd-01-domain-design-template.md
91
+ │ │ │ ├── ddd-02-logical-design-template.md
92
+ │ │ │ ├── ddd-03-test-report-template.md
93
+ │ │ │ └── adr-template.md
94
+ │ │ │
95
+ │ │ └── standards/ # Standards templates
96
+ │ │ ├── tech-stack.md
97
+ │ │ ├── coding-standards.md
98
+ │ │ └── system-architecture.md
99
+ │ │
100
+ │ ├── operations/ # Operations phase templates
101
+ │ │ └── deployment-unit-template.md
102
+ │ │
103
+ │ └── standards/ # Standards facilitation guides
104
+ │ ├── catalog.yaml # Standards registry
105
+ │ ├── tech-stack.guide.md # Tech stack facilitation
106
+ │ ├── coding-standards.guide.md # Coding standards facilitation
107
+ │ └── data-stack.guide.md # Data stack facilitation
108
+
109
+ ├── commands/ # Slash command definitions
110
+ │ ├── iris-master-agent.md # /iris-master-agent command
111
+ │ ├── iris-inception-agent.md # /iris-inception-agent command
112
+ │ ├── iris-construction-agent.md # /iris-construction-agent command
113
+ │ └── iris-operations-agent.md # /iris-operations-agent command
114
+
115
+ ├── memory-bank.yaml # Memory bank schema (source of truth)
116
+ ├── context-config.yaml # Context loading configuration
117
+ ├── quick-start.md # Quick start guide
118
+ └── README.md # This file
119
+ ```
120
+
121
+ ---
14
122
 
15
123
  ## Three Phases
16
124
 
@@ -19,42 +127,44 @@ AI-DLC is an **AWS methodology** for AI-native software development that optimiz
19
127
  **Goal**: Complete planning and design before construction begins
20
128
 
21
129
  **Activities**:
22
-
23
- - Gather requirements
24
- - Create user stories
25
- - Design architecture
26
- - Decompose into Units of Work
27
- - Plan Bolt instances
130
+ - Capture intents (high-level goals)
131
+ - Gather requirements (functional and non-functional)
132
+ - Assess risks (technical, business, operational)
133
+ - Define system context and boundaries
134
+ - Decompose into deployable units
135
+ - Create user stories with acceptance criteria
136
+ - Plan bolts for construction
28
137
 
29
138
  **Command**: `/iris-inception-agent --intent="intent-name"`
30
139
 
31
- **Output**:
32
-
33
- - Requirements documented
34
- - Stories created
35
- - Architecture designed
36
- - Units decomposed
37
- - Bolts planned
140
+ **Outputs**:
141
+ - PRFAQ document
142
+ - Requirements with measurement criteria
143
+ - Risk assessment
144
+ - System context diagram
145
+ - Unit decomposition
146
+ - User stories
147
+ - Bolt plans
38
148
 
39
149
  ### 2. Construction Phase
40
150
 
41
151
  **Goal**: Build working software through iterative bolt execution
42
152
 
43
153
  **Activities**:
44
-
45
154
  - Execute bolts through DDD stages:
46
- 1. **domain-design** - Model business logic
47
- 2. **logical-design** - Apply NFRs and patterns
48
- 3. **code-generation** - Implement code
49
- 4. **testing** - Automated testing
155
+ 1. **Domain Design** - Model business logic using DDD principles
156
+ 2. **Logical Design** - Apply NFRs and architectural patterns
157
+ 3. **ADR Analysis** - Document architectural decisions (optional)
158
+ 4. **Code Generation** - Generate production code
159
+ 5. **Testing** - Verify with automated tests
50
160
 
51
161
  **Command**: `/iris-construction-agent --unit="unit-name"`
52
162
 
53
- **Output**:
54
-
55
- - Domain models
56
- - Logical designs
57
- - Implementation code
163
+ **Outputs**:
164
+ - Domain design documents
165
+ - Logical design documents
166
+ - Architectural Decision Records (ADRs)
167
+ - Production code with story traceability
58
168
  - Comprehensive tests
59
169
 
60
170
  ### 3. Operations Phase
@@ -62,36 +172,43 @@ AI-DLC is an **AWS methodology** for AI-native software development that optimiz
62
172
  **Goal**: Deploy and operate the system
63
173
 
64
174
  **Activities**:
65
-
66
- - Build deployment artifacts
67
- - Deploy to environments
68
- - Verify deployments
69
- - Setup monitoring
175
+ - Build deployment artifacts (containers, functions, bundles)
176
+ - Deploy through environments (Dev → Staging → Production)
177
+ - Verify deployments with health checks
178
+ - Setup monitoring, alerts, and SLOs
179
+ - Handle rollbacks when needed
70
180
 
71
181
  **Command**: `/iris-operations-agent --unit="unit-name"`
72
182
 
73
- **Output**:
74
-
75
- - Deployed services
183
+ **Outputs**:
184
+ - Deployment units
76
185
  - Monitoring dashboards
186
+ - Alert configurations
187
+ - Runbooks/playbooks
77
188
  - Deployment documentation
78
189
 
79
- ## Artifact Ownership Matrix
190
+ ---
80
191
 
81
- | Phase / Agent | Primary Output Artifacts | Description |
82
- |--------------|-------------------------|-------------|
83
- | **Inception** | **Requirements** | Functional & Non-functional requirements |
84
- | | **Stories** | User stories scoped to a Unit |
85
- | | **System Context** | High-level boundaries & actors |
86
- | | **Unit Decomposition** | Identification of independent units |
87
- | | **Bolt Plans** | Planned work sessions |
88
- | **Construction** | **Domain Design** | Entities, Aggregates, Value Objects |
89
- | | **Logical Design** | APIs, Schemas, Cloud Resources |
90
- | | **Code** | Source code implementation |
91
- | | **Tests** | Unit, Integration, & E2E tests |
92
- | **Operations** | **Build Artifacts** | Docker images, binaries, bundles |
93
- | | **Infrastructure** | Terraform/CloudFormation/CDK |
94
- | | **Documentation** | Runbooks, API docs |
192
+ ## Project Scenarios
193
+
194
+ ### Greenfield (New Projects)
195
+ Starting fresh with no existing code:
196
+ 1. Initialize project with standards
197
+ 2. Begin Inception phase immediately
198
+ 3. Build from scratch using AI-DLC methodology
199
+
200
+ ### Brownfield (Existing Codebases)
201
+ Adding features to existing code:
202
+ 1. Initialize project with standards
203
+ 2. **Run code elevation** to analyze existing codebase
204
+ 3. AI creates static and dynamic models for context
205
+ 4. Begin Inception with full codebase understanding
206
+
207
+ **Code Elevation Process**:
208
+ - **Static Model**: Components, responsibilities, and relationships
209
+ - **Dynamic Model**: How components interact for significant use cases
210
+
211
+ ---
95
212
 
96
213
  ## Decomposition Hierarchy
97
214
 
@@ -110,7 +227,6 @@ Intent (feature/capability)
110
227
  **Bolts** are time-boxed execution sessions scoped to a **Unit**. A Unit may require multiple Bolts to complete all its Stories.
111
228
 
112
229
  **Example**:
113
-
114
230
  - **Intent**: User Authentication
115
231
  - **Unit**: Auth Service
116
232
  - **Story 1**: User Registration
@@ -118,255 +234,283 @@ Intent (feature/capability)
118
234
  - **Bolt 1**: Implement Registration (executes Story 1)
119
235
  - **Bolt 2**: Implement Login (executes Story 2)
120
236
 
121
- ## Agent Capabilities & Slash Commands
237
+ ---
238
+
239
+ ## Artifact Ownership Matrix
240
+
241
+ | Phase / Agent | Primary Output Artifacts | Description |
242
+ |--------------|-------------------------|-------------|
243
+ | **Master** | **project.yaml** | Project configuration and scenario |
244
+ | | **standards/** | Tech stack, coding standards, architecture |
245
+ | | **elevation/** | Static and dynamic models (brownfield) |
246
+ | **Inception** | **requirements.md** | Functional & non-functional requirements |
247
+ | | **prfaq.md** | Press Release / FAQ document |
248
+ | | **risks.md** | Risk assessment with mitigations |
249
+ | | **system-context.md** | High-level boundaries & actors |
250
+ | | **units.md** | Unit decomposition overview |
251
+ | | **stories/** | User stories scoped to units |
252
+ | | **bolt plans** | Planned work sessions |
253
+ | **Construction** | **domain-design.md** | Entities, Aggregates, Value Objects |
254
+ | | **logical-design.md** | APIs, Schemas, Cloud Resources |
255
+ | | **adr-*.md** | Architectural Decision Records |
256
+ | | **test-report.md** | Test results and coverage |
257
+ | | **Source Code** | Production code implementation |
258
+ | **Operations** | **deployment-units/** | Packaged artifacts documentation |
259
+ | | **playbooks/** | Incident response runbooks |
260
+ | | **Monitoring** | Dashboards, alerts, SLOs |
261
+
262
+ ---
122
263
 
123
- ### Core Agent Commands (Slash Commands)
264
+ ## Agent Commands & Skills
124
265
 
125
- These are the primary entry points defined in `.cursor/commands` (or your agentic coding tool's equivalent), mapping to `src/flows/aidlc/commands/`:
266
+ ### Master Agent (`/iris-master-agent`)
126
267
 
127
- - `/iris-master-agent` - **Start Here**. The Master Orchestrator that routes you to the right place.
128
- - `/iris-inception-agent` - Start Inception phase
129
- - `/iris-construction-agent` - Start Construction phase
130
- - `/iris-operations-agent` - Start Operations phase
268
+ The central orchestrator and entry point.
131
269
 
132
- ### Agent Skills (Internal)
270
+ | Skill | Purpose |
271
+ |-------|---------|
272
+ | `project-init` | Initialize project with standards |
273
+ | `code-elevate` | Analyze existing codebase (brownfield) |
274
+ | `analyze-context` | View current project state |
275
+ | `route-request` | Get directed to the right agent |
276
+ | `explain-flow` | Learn about AI-DLC methodology |
277
+ | `answer-question` | Get help with any iris question |
133
278
 
134
- Agents execute these skills internally. You generally don't run these directly as slash commands, but the agents use them to perform work.
279
+ ### Inception Agent (`/iris-inception-agent --intent="name"`)
135
280
 
136
- - **Inception**: Gather Requirements, Create Stories, Define Context, Decompose Units
137
- - **Construction**: Plan Bolts, Start Bolts, Manage Bolt Status
138
- - **Operations**: Build, Deploy, Verify
281
+ Handles the planning phase.
139
282
 
140
- ## Memory Bank Structure
283
+ | Skill | Purpose |
284
+ |-------|---------|
285
+ | `navigator` | Navigate inception workflow |
286
+ | `intent-create` | Create a new intent with PRFAQ |
287
+ | `intent-list` | List all intents |
288
+ | `requirements` | Gather requirements with measurements |
289
+ | `risks` | Assess risks (likelihood, impact, mitigations) |
290
+ | `context` | Define system context |
291
+ | `units` | Decompose into units |
292
+ | `story-create` | Create stories for a unit |
293
+ | `bolt-plan` | Plan bolts for stories |
294
+ | `review` | Review inception artifacts |
295
+
296
+ ### Construction Agent (`/iris-construction-agent --unit="name"`)
297
+
298
+ Handles the building phase.
141
299
 
142
- > **Note**: The structure below is an **example**. The authoritative source of truth for the memory bank schema is `.iris/aidlc/memory-bank.yaml`. Agents read that file to determine where to place artifacts.
300
+ | Skill | Purpose |
301
+ |-------|---------|
302
+ | `navigator` | Navigate construction workflow |
303
+ | `bolt-list` | List all bolts with status |
304
+ | `bolt-start` | Start/continue executing a bolt |
305
+ | `bolt-status` | Check bolt progress |
306
+ | `bolt-replan` | Replan bolts if needed |
143
307
 
144
- All artifacts are stored in the `memory-bank/` directory:
308
+ ### Operations Agent (`/iris-operations-agent --unit="name"`)
309
+
310
+ Handles the deployment phase.
311
+
312
+ | Skill | Purpose |
313
+ |-------|---------|
314
+ | `navigator` | Navigate operations workflow |
315
+ | `build` | Build deployment artifacts |
316
+ | `deploy` | Deploy to environment |
317
+ | `verify` | Verify deployment |
318
+ | `monitor` | Set up monitoring and SLOs |
319
+ | `rollback` | Rollback to previous version |
320
+
321
+ ---
322
+
323
+ ## Bolt Types
324
+
325
+ | Type | Best For | Stages |
326
+ |------|----------|--------|
327
+ | **DDD Construction** | Complex business logic, domain modeling | Domain Design → Logical Design → ADR (optional) → Code Generation → Testing |
328
+ | **Simple Construction** | UI, integrations, utilities | Plan → Code Generation → Testing |
329
+ | **Spike** | Research, exploration, unknowns | Research → Document → Recommend |
330
+
331
+ ---
332
+
333
+ ## Memory Bank Structure
334
+
335
+ All artifacts are stored in `memory-bank/` (schema defined in `memory-bank.yaml`):
145
336
 
146
337
  ```text
147
338
  memory-bank/
339
+ ├── project.yaml # Project configuration
340
+
341
+ ├── elevation/ # Brownfield code analysis
342
+ │ ├── static-model.md # Components, responsibilities, relationships
343
+ │ └── dynamic-model.md # Use case interactions
344
+
148
345
  ├── intents/ # Feature intents
149
- │ └── {intent-name}/
346
+ │ └── {NNN}-{intent-name}/
150
347
  │ ├── requirements.md # Functional & non-functional requirements
151
- │ ├── system-context.md # High-level boundaries & actors
348
+ │ ├── prfaq.md # Press Release / FAQ
349
+ │ ├── risks.md # Risk assessment
350
+ │ ├── system-context.md # System boundaries & actors
152
351
  │ ├── units.md # Unit decomposition overview
153
352
  │ └── units/
154
- │ └── {unit-name}/
353
+ │ └── {UUU}-{unit-name}/
155
354
  │ ├── unit-brief.md # Unit scope and details
156
355
  │ └── stories/
157
356
  │ ├── 001-{title}.md
158
357
  │ └── 002-{title}.md
358
+
159
359
  ├── bolts/ # Bolt execution records
160
- │ └── {bolt-id}/
360
+ │ └── {BBB}-{unit-name}/
161
361
  │ ├── bolt.md # Bolt instance metadata
162
- │ ├── ddd-01-domain-model.md # Stage 1: Domain modeling
163
- │ ├── ddd-02-technical-design.md # Stage 2: Technical design
362
+ │ ├── ddd-01-domain-design.md # Stage 1: Domain design
363
+ │ ├── ddd-02-logical-design.md # Stage 2: Logical design
364
+ │ ├── adr-{N}-{slug}.md # Stage 3: ADR (optional)
164
365
  │ └── ddd-03-test-report.md # Stage 5: Test report
366
+
165
367
  ├── standards/ # Project standards
166
368
  │ ├── tech-stack.md
167
369
  │ ├── coding-standards.md
168
- └── system-architecture.md
370
+ ├── system-architecture.md
371
+ │ ├── api-conventions.md
372
+ │ └── ux-guide.md
373
+
169
374
  └── operations/ # Deployment context
375
+ ├── deployment-units/
376
+ │ └── {unit-name}.md
377
+ └── playbooks/
378
+ ├── high-error-rate.md
379
+ ├── high-latency.md
380
+ └── service-down.md
170
381
  ```
171
382
 
172
- ## Quick Start Guide
173
-
174
- ### 1. Create Your First Intent
175
-
176
- Open your AI coding tool (Claude Code, Cursor, etc.) and type:
177
-
178
- ```text
179
- /iris-master-agent
180
- ```
181
-
182
- Then type `intent-create` to create your intent (e.g., "user-authentication").
183
-
184
- ### 2. Run Inception Phase
185
-
186
- ```text
187
- /iris-inception-agent --intent="user-authentication"
188
- ```
189
-
190
- Work through the Inception menu:
191
-
192
- 1. Gather Requirements
193
- 2. Create Stories
194
- 3. Design Architecture
195
- 4. Decompose into Units
196
- 5. Plan Bolts
197
- 6. Review & Complete
198
-
199
- ### 3. Execute Construction
200
-
201
- ```text
202
- /iris-construction-agent --unit="auth-service"
203
- ```
204
-
205
- Start your first bolt and work through the DDD stages:
206
-
207
- 1. Domain Design
208
- 2. Logical Design
209
- 3. Code Generation
210
- 4. Testing
211
-
212
- ### 4. Deploy with Operations
213
-
214
- ```text
215
- /iris-operations-agent --unit="auth-service"
216
- ```
217
-
218
- Deploy your unit:
219
-
220
- 1. Build Deployment Artifacts
221
- 2. Deploy to Environment
222
- 3. Verify Deployment
223
- 4. Setup Monitoring
383
+ ---
224
384
 
225
385
  ## Key Principles
226
386
 
227
- ### 1. Mob Elaboration (Rapid Planning)
228
-
229
- AI-DLC uses **concentrated rapid planning** during Inception. Instead of distributing planning across multiple sprints, you complete all planning in hours (not weeks) to give AI complete cross-unit context.
230
-
231
- ### 2. AI Plans, Human Validates
232
-
233
- The AI suggests decompositions and designs, but humans review and approve all decisions.
387
+ ### 1. AI Drives, Human Validates
388
+ AI proposes plans, decompositions, and implementations. Humans review and approve at checkpoints.
234
389
 
235
- ### 3. Bolts are Flexible
390
+ ### 2. Human Oversight as Loss Function
391
+ Validation at each step catches errors early before they cascade downstream.
236
392
 
237
- Bolts take "hours or days" depending on complexity - they're not fixed-duration like sprints.
393
+ ### 3. Mob Elaboration
394
+ Concentrated rapid planning during Inception. Complete all planning in hours, not weeks.
238
395
 
239
- ### 4. DDD Focus
396
+ ### 4. Bolts are Flexible
397
+ Bolts take "hours or days" depending on complexity - not fixed-duration like sprints.
240
398
 
241
- Domain-Driven Design principles guide the entire Construction phase.
242
-
243
- ### 5. Persistent Context
399
+ ### 5. DDD Focus
400
+ Domain-Driven Design principles guide the Construction phase with proper separation of concerns.
244
401
 
402
+ ### 6. Persistent Context
245
403
  Everything is stored in the memory bank so context is never lost between sessions.
246
404
 
405
+ ---
406
+
247
407
  ## Workflow Example
248
408
 
249
409
  Here's a complete workflow for building a feature:
250
410
 
251
- 1. **Create Intent**
252
-
253
- ```text
254
- /iris-master-agent
255
- # Then type: intent-create
256
- # Create "user-authentication" intent
257
- ```
411
+ ### 1. Initialize Project
258
412
 
259
- 2. **Inception Phase**
260
-
261
- ```text
262
- /iris-inception-agent --intent="user-authentication"
263
- # Complete all inception activities
264
- # Result: 2 units planned with 3 bolts total
265
- ```
413
+ ```text
414
+ /iris-master-agent
415
+ # Then type: project-init
416
+ # Set up tech stack and coding standards
417
+ ```
266
418
 
267
- 3. **Construction - Unit 1**
419
+ ### 2. Create Intent (Inception Phase)
268
420
 
269
- ```text
270
- /iris-construction-agent --unit="auth-service"
271
- # Execute auth-service-bolt-1 through all stages
272
- # Execute auth-service-bolt-2 through all stages
273
- # Result: Auth service fully implemented and tested
274
- ```
421
+ ```text
422
+ /iris-inception-agent --intent="user-authentication"
423
+ # Work through:
424
+ # - requirements (FR/NFR)
425
+ # - risks
426
+ # - context
427
+ # - units
428
+ # - stories
429
+ # - bolt-plan
430
+ # - review
431
+ ```
275
432
 
276
- 4. **Construction - Unit 2**
433
+ ### 3. Execute Bolts (Construction Phase)
277
434
 
278
- ```text
279
- /iris-construction-agent --unit="email-service"
280
- # Execute email-service-bolt-1
281
- # Result: Email service implemented
282
- ```
435
+ ```text
436
+ /iris-construction-agent --unit="auth-service"
437
+ # Execute each bolt through stages:
438
+ # 1. Domain Design
439
+ # 2. Logical Design
440
+ # 3. ADR Analysis (optional)
441
+ # 4. Code Generation
442
+ # 5. Testing
443
+ ```
283
444
 
284
- 5. **Operations**
445
+ ### 4. Deploy (Operations Phase)
285
446
 
286
- ```text
287
- /iris-operations-agent --unit="auth-service"
288
- # Build, deploy, verify
289
- # Result: Auth service running in production
447
+ ```text
448
+ /iris-operations-agent --unit="auth-service"
449
+ # - build
450
+ # - deploy (Dev Staging → Production)
451
+ # - verify
452
+ # - monitor
453
+ ```
290
454
 
291
- /iris-operations-agent --unit="email-service"
292
- # Build, deploy, verify
293
- # Result: Email service running in production
294
- ```
455
+ ---
295
456
 
296
457
  ## Tips for Success
297
458
 
298
- ### Planning
299
-
300
- - Be thorough in Inception - it pays off during Construction
301
- - Document NFRs clearly - they affect logical design
459
+ ### Planning (Inception)
460
+ - Be thorough - it pays off during Construction
461
+ - Document NFRs with measurable criteria
462
+ - Assess risks early with mitigations
302
463
  - Group related stories into the same bolt
303
464
 
304
- ### Construction
305
-
465
+ ### Building (Construction)
306
466
  - Follow the DDD stages in order
307
467
  - Don't skip testing
308
468
  - Keep bolts focused (5-8 stories max)
309
- - Update memory bank artifacts as you progress
310
-
311
- ### Operations
469
+ - Document significant decisions as ADRs
312
470
 
471
+ ### Deploying (Operations)
313
472
  - Always deploy to staging first
314
473
  - Run smoke tests after every deployment
315
474
  - Setup monitoring from the start
316
475
  - Document runbooks for on-call engineers
317
476
 
318
- ## Agents
319
-
320
- Three specialized agents guide you through AI-DLC:
321
-
322
- 1. **Master Orchestrator** (`agents/master-agent.md`)
323
- - Central entry point
324
- - Workflow routing
325
- - State analysis
477
+ ---
326
478
 
327
- 2. **Inception Agent** (`agents/inception-agent.md`)
328
- - Requirements gathering
329
- - Story creation
330
- - Architecture design
331
- - System Context definition
332
- - Unit decomposition
333
- - Bolt planning
479
+ ## Getting Help
334
480
 
335
- 3. **Construction Agent** (`agents/construction-agent.md`)
336
- - Bolt execution
337
- - DDD stage guidance
338
- - Code generation
339
- - Testing
481
+ If you get stuck:
340
482
 
341
- 4. **Operations Agent** (`agents/operations-agent.md`)
342
- - Build artifacts
343
- - Deployment
344
- - Verification
345
- - Monitoring
483
+ 1. **Ask the Agent**: Just ask the Master or any agent your question. They can read the memory bank directly.
346
484
 
347
- ## Learn More
485
+ 2. **Explain Flow**: Type `explain-flow` with the Master Agent to learn about AI-DLC methodology.
348
486
 
349
- - **Official AI-DLC Documentation**: See `/resource/aidlc-pdf-dump.txt` in the iris repository
350
- - **Methodology Notes**: See `memory-bank/research/` for methodology research
351
- - **Agent Details**: Read the agent files in `.iris/aidlc/agents/`
487
+ 3. **Answer Question**: Type `answer-question` followed by your question.
352
488
 
353
- ## Getting Help
489
+ 4. **Quick Start Guide**: See `quick-start.md` in this directory.
354
490
 
355
- If you get stuck:
491
+ 5. **Glossary**: See `memory-bank/glossary.md` for terminology.
356
492
 
357
- 1. **Ask the Agent**: Just ask the Master or any agent your question. They can read the memory bank directly.
493
+ ---
358
494
 
359
495
  ## Customization
360
496
 
361
497
  You can customize this flow by editing:
362
498
 
363
- - `.iris/aidlc/memory-bank.yaml` - Memory bank structure
499
+ - `memory-bank.yaml` - Memory bank structure
364
500
  - `agents/*-agent.md` - Agent directives and behaviors
501
+ - `skills/**/*.md` - Skill implementations
502
+ - `templates/**/*.md` - Artifact templates
365
503
  - `commands/*.md` - Slash command definitions
366
- - `.iris/aidlc/templates/` - Templates used by agents
367
504
 
368
505
  ---
369
506
 
370
- **Happy building with AI-DLC!** 🚀
507
+ ## Learn More
508
+
509
+ - **Quick Start Guide**: `quick-start.md`
510
+ - **Glossary**: `memory-bank/glossary.md`
511
+ - **AI-DLC Specification**: `/resources/ai-dlc-specification.md`
512
+ - **Agent Details**: `agents/` directory
513
+
514
+ ---
371
515
 
372
516
  *This is the official AI-DLC implementation by iris, following the AWS AI-DLC methodology.*