1# Workflow
2An iteration-based workflow designed to keep planning light, execution focused, and documentation useful.
3
4## Core Operating Rules
51. Project hierarchy: iteration → slice → task.
62. Every iteration delivers the finest production-grade quality; avoid "MVP", "POC", or "prototype" mindsets.
73. Plan at the iteration level, not at the task-list level.
84. Handle the active iteration and active slice only.
95. Never invent a full task breakdown for a slice.
106. Focus on only the next implementation task.
117. For light work, a slice may consist of a single implementation task.
128. Verify each completed task before treating it as done.
139. Record outcomes, not implementation details.
1410. Never make technical or product decisions without discussion.
1511. Follow the Red-Green-Refactor (RGR) cycle for implementation work.
16
17## Communication Style
18- Keep answers short and concise.
19- Put the punchline in the first sentence.
20- No fluff or cheerful filler text; technical prose only.
21- Do not praise my questions or validate my premises.
22- Avoid polite hedging or opinion-based preambles.
23- Call out bad news and technical flaws directly.
24- If I'm wrong, say so immediately even if I push back.
25- Do not anchor on my ideas; generate yours independently.
26- Use explicit confidence levels for assessments.
27
28## Project Documentation Structure
29```text
30.building/
31 product.md
32 design.md
33 iterations.md
34 i1-foundation/
35 spec.md
36 plan.md
37 changelog.md
38 i2-core-feature/
39 i3-extension/
40```
41
42### `.building/product.md`
43Defines product context, goals, and business intent.
44
45### `.building/design.md`
46Defines guidelines for UI (e.g., layout, typography, and colors) or technical design (e.g., backend module architecture, API design patterns).
47
48### `.building/iterations.md`
49Tracks iteration status across the project.
50
51### `.building/<iteration>/spec.md`
52Defines what the iteration must achieve.
53
54Must include:
55- objective
56- user or business outcome
57- constraints
58- non-goals
59- success criteria
60
61This is the source of truth for iteration scope.
62
63### `.building/<iteration>/plan.md`
64Defines the implementation approach for the iteration.
65
66Must include:
67- overview
68- iteration decisions
69- slice status list
70- slice definitions
71- slice-specific decisions when needed
72
73Do not predefine implementation tasks for slices.
74
75### `.building/<iteration>/changelog.md`
76A record of execution for the iteration.
77
78Purpose:
79- preserve meaningful implementation history
80- keep the current state obvious
81- help determine the next task
82
83Add one entry for each completed task-sized unit of work, ordered newest first.
84
85Write each entry as a direct, concise outcome, not the mechanical change.
86
87## Execution Flow
88When executing work, always follow this sequence:
89
901. Identify the active iteration.
912. Read `spec.md`, `plan.md`, and recent `changelog.md` entries for that iteration.
923. Identify the active slice.
934. Assess progress against the slice exit criteria.
945. Propose the single next implementation task.
956. Wait for user confirmation before implementing.
967. Implement the task.
978. Verify the result.
989. Update the changelog and iteration/slice statuses to reflect current progress.
99
100## Agentic TDD Protocol
101For implementation work, you must follow the RGR cycle to clarify your intent and deliver finest code quality—they are your success metrics.
102
103### The RGR Cycle
1041. RED
105 - Goal: Write one or more failing tests that define the desired behavior.
106 - Action: Modify test files. Verify fail. Commit.
1072. GREEN
108 - Goal: Write the minimum implementation code to make the tests pass.
109 - Action: Modify source files. Verify pass. Commit.
1103. REFACTOR
111 - Goal: Improve code structure, readability, or performance without changing behavior.
112 - Action: Modify source and/or test files. Verify pass. Do not commit.
113 - Approval: Wait for user acceptance test result.
114
115### Principles of Engagement
116- Write failing tests before writing any feature code for a given scope.
117- Execute tests at every phase change to physically verify failure or success.
118- Include specific test results and error messages in your thought process.
119- Flawed tests can be corrected during the green phase. Document the reasoning in the commit.
120- Keep commits granular to represent single steps in the RGR cycle.
121
122## Task Proposal
123When asked `What next?`, propose one implementation task that moves the active slice toward its exit criteria.
124
125Write task proposals in plain English. Use concise, direct sentences that are easy to skim.
126
127Task documentation:
128- Save the task plan to a file under `docs/` for review.
129- After completing the task, create a short, skimmable UAT checklist.
130
131## Double-Check
132When prompted with `Double-check!`, review the work from the current session for completeness.
133
134For a task proposal, review the plan with fresh eyes and identify anything that should be clarified or decided before implementation begins.
135
136## Status Values
137Allowed statuses for iterations and slices:
138
139- `[ ]` todo
140- `[.]` in progress
141- `[x]` done
142- `[?]` blocked
143- `[-]` cancelled
144
145## ID Formats
146- Iteration: `I1`, `I2`, `I3`
147- Slice: `S1`, `S2`, `S3`
148- Task: `01`, `02`, `03`
149- Work ID: `I1-S1-01`, `I1-S1-02`
150
151## Commit Rule
152Remove temporary documents, including the task proposal and the UAT checklist, before committing.
153
154Use the Work ID as the scope in the commit message for implementation tasks.
155
156Commit format:
157- Red Phase: `test(I1-S2-03): failing test for auth redirect`
158- Green Phase: `feat(I1-S2-03): enforce auth redirect`
159- Refactor Phase: `refactor(I1-S2-03): clean up redirect logic`
160- Other: `chore: update CI config`, `docs: add auth module README`
161
162## Document Templates
163
164### `.building/iterations.md`
165```md
166# Iteration Status
167- [.] [I1 Foundation](i1-foundation/plan.md)
168- [ ] [I2 Core Features](i2-core-features/plan.md)
169- [ ] [I3 Advanced Tools](i3-advanced-tools/plan.md)
170```
171
172### `.building/<iteration>/plan.md`
173```md
174# I1 Foundation Plan
175
176## Overview
177
178## Iteration Decisions
179
180## Slice Status
181- [x] [S1 Repository Foundation](#s1-repository-foundation)
182- [.] [S2 Auth and Workspace Shell](#s2-auth-and-workspace-shell)
183- [ ] [S3 Core CRUD](#s3-core-crud)
184
185## S1 Repository Foundation
186### Goal
187### Scope
188### Non-goals
189### Dependencies
190### Exit Criteria
191### Slice Decisions
192```
193
194### `.building/<iteration>/changelog.md`
195```md
196# I1 Foundation Changelog
197
198## I1-S2-03 — 2026-03-25
199Unauthenticated users are redirected to sign-in before accessing the workspace.
200```
201
202### Task Proposal
203```md
204# Title
205## Goal
206## Scope
207## Done when
208## Decisions
209## Approach
210```
211