You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .roo/rules/rules.md
+7Lines changed: 7 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,12 @@
1
1
# Code Quality Rules
2
2
3
+
## Governance Alignment
4
+
5
+
- Use `integration` as the canonical working and PR target branch. Short-lived branches must branch from and merge back into `integration`; do not use `main` as the ordinary development base.
6
+
- Scale planning to scope, risk, reversibility, and complexity. Trivial low-risk changes may use a brief checklist; substantial or high-risk work requires proportionate research, design, planning, and review.
7
+
- Use the virtual Spec Workspace as the canonical home for agent-created requirements, designs, and implementation plans. Create repository planning documents only when the user, maintainer, or durable-record policy explicitly requires them.
8
+
- Do not provide effort or elapsed-time estimates unless the user or maintainer explicitly requests them.
9
+
3
10
1. Test Coverage:
4
11
5
12
- Before attempting completion, always make sure that any code changes have test coverage
Copy file name to clipboardExpand all lines: AGENTS.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,8 +36,8 @@ Before making ANY changes, be aware of these already-implemented systems:
36
36
37
37
### 1. Governance System
38
38
39
-
-**`WORKSPACE_GOVERNANCE.md`** — Absolute rules: no shortcuts, no cheating, plan first, no half-work, industry standard quality.
40
-
-**`PLANNING_REQUIRED.md`** — 5-stage pipeline: Research -> Design -> Plan -> Review -> Execute. Zero code without a plan.
39
+
-**`WORKSPACE_GOVERNANCE.md`** — Absolute rules: no shortcuts, no cheating, risk-proportionate planning, no half-work, industry standard quality.
40
+
-**`PLANNING_REQUIRED.md`** — Scale planning to change risk and complexity. Agent-created plans live canonically in the virtual Spec Workspace; repository planning documents are created only when a maintainer or task explicitly requires them.
41
41
-**`docs/ARCHITECTURE.md`** — Full architecture reference.
# 📐 Planning Required — Scale Planning to the Change
2
2
3
-
> **RULE: Zero code without a plan. This is not optional.**
3
+
> **RULE: Plan in proportion to risk and complexity.**
4
4
>
5
-
> Every task — no matter how small — must go through this pipeline before implementation begins.
5
+
> Every task requires deliberate scope and verification, but trivial changes do not require a universal five-stage document pipeline.
6
6
7
7
---
8
8
9
-
## The Pipeline (5 Stages, No Skipping)
9
+
## Choose the Planning Level
10
+
11
+
Assess blast radius, complexity, reversibility, uncertainty, security/privacy impact, data or API compatibility, and cross-module dependencies.
12
+
13
+
### Level 1 — Trivial / Low Risk
14
+
15
+
Use a brief task checklist or equivalent working notes. Examples include typo corrections, narrow documentation cleanup, formatting-only changes, and obvious localized fixes with no behavioral uncertainty.
16
+
17
+
Required:
18
+
19
+
- Identify the intended change and affected files.
20
+
- Preserve unrelated content.
21
+
- Run targeted verification appropriate to the change.
22
+
23
+
### Level 2 — Standard
24
+
25
+
Use a concise implementation plan for bounded features, fixes, or refactors with understood dependencies and moderate blast radius.
26
+
27
+
Required:
28
+
29
+
- Confirm current behavior and relevant existing patterns.
30
+
- Record scope, implementation steps, risks, and verification.
31
+
- Review the plan before execution and update it if discoveries materially change scope.
32
+
33
+
### Level 3 — High Risk / Architectural
34
+
35
+
Use the full workflow for architectural changes, migrations, security-sensitive work, broad refactors, cross-package contracts, difficult-to-reverse changes, or work with significant uncertainty:
10
36
11
37
```
12
38
1. RESEARCH → 2. DESIGN → 3. PLAN → 4. REVIEW → 5. EXECUTE
13
39
```
14
40
41
+
Required:
42
+
43
+
- Document current behavior, constraints, dependencies, alternatives, and failure modes.
44
+
- Define the proposed design, affected interfaces, compatibility implications, and test strategy.
45
+
- Produce a stepwise implementation and rollback plan.
46
+
- Obtain the level of review required by the task or maintainers before execution.
47
+
15
48
---
16
49
17
-
## Stage 1: Research
50
+
## Canonical Location for Agent-Created Plans
18
51
19
-
Before writing a single line, answer these questions in `docs/research/<topic>.md`:
52
+
The **virtual Spec Workspace** is canonical for agent-created requirements, designs, and implementation plans. Use its requirements, design, and tasks documents as appropriate.
53
+
54
+
Do **not** create repository planning Markdown by default. Create or update a repository document under `docs/research/`, `docs/plans/`, or `docs/decisions/` only when:
55
+
56
+
- the user or maintainer explicitly requests a repository-visible artifact or path;
57
+
- the artifact is intended for version control, contributor review, release evidence, or long-term project history; or
58
+
- repository policy requires an ADR or another durable record for the decision.
59
+
60
+
When a repository artifact is required, keep it consistent with the canonical Spec Workspace while work is active. Accepted ADRs and other explicitly versioned records remain authoritative repository history for their subject.
61
+
62
+
---
63
+
64
+
## Research Guidance
65
+
66
+
For Level 2 or Level 3 work, answer the relevant questions in the virtual Spec Workspace or an explicitly requested repository research document:
20
67
21
68
- What is the exact problem or feature being addressed?
22
-
- What existing code is involved? (Read all affected files fully.)
23
-
- What does the current behavior look like? (Run it, test it, observe it.)
24
-
- What are the constraints? (Performance, compatibility, API limits, bundle size?)
25
-
-What have others done? (Check existing patterns in this codebase first.)
69
+
- What existing code is involved?
70
+
- What does the current behavior look like?
71
+
- What constraints apply, including performance, compatibility, API limits, or bundle size?
72
+
-Which existing codebase patterns should be followed?
26
73
- What could go wrong?
27
74
28
-
**Minimum time: Do not rush this. A missed dependency here = broken code later.**
75
+
Depth matters; elapsed time does not. Do not impose or promise minimum planning durations.
29
76
30
77
---
31
78
32
-
## Stage 2: Design
79
+
## Design Guidance
33
80
34
-
Write a design document in `docs/decisions/<ADR-NNN-topic>.md`:
81
+
For Level 3 work, capture:
35
82
36
-
- Proposed solution (with rationale)
37
-
- Alternative approaches considered (and why rejected)
38
-
- Data flow / sequence diagram if applicable
39
-
- API surface changes (if any)
40
-
- Types / interfaces affected
41
-
- Test strategy
83
+
- Proposed solution and rationale
84
+
- Alternative approaches considered and why they were rejected
85
+
- Data flow or sequence diagram if applicable
86
+
- API surface and types/interfaces affected
87
+
- Compatibility, migration, rollback, and test strategy
88
+
89
+
Create an ADR in `docs/decisions/` only when the decision needs an explicitly versioned, durable architectural record.
42
90
43
91
---
44
92
45
-
## Stage 3: Plan
93
+
## Implementation Plan Template
46
94
47
-
Create an implementation plan in `docs/plans/<task-name>.md` using this template:
95
+
Use the virtual Spec Workspace tasks document by default. If a repository plan is explicitly required, this template may be used at the requested path:
48
96
49
97
```markdown
50
98
# Implementation Plan: <TaskName>
@@ -61,16 +109,13 @@ One sentence: what does this accomplish?
61
109
- Packages affected: []
62
110
63
111
## Steps
64
-
-[ ] Step 1 — description (estimated: X min)
112
+
-[ ] Step 1 — description
65
113
-[ ] Step 2 — description
66
114
-[ ] Step 3 — description
67
-
...
68
115
69
116
## Verification
70
-
-[ ]`pnpm check-types` passes
71
-
-[ ]`pnpm test` passes (relevant test suites)
72
-
-[ ]`pnpm lint` passes
73
-
-[ ] Manual test: [describe what to verify visually/functionally]
117
+
-[ ] Targeted type checks, tests, and lint selected for the affected scope
118
+
-[ ] Manual test: [describe what to verify visually/functionally, if applicable]
74
119
75
120
## Risks
76
121
- Risk 1: [mitigation]
@@ -81,41 +126,33 @@ One sentence: what does this accomplish?
81
126
- Blocks: [other tasks/PRs]
82
127
```
83
128
129
+
Do not add effort or elapsed-time estimates unless the user or maintainer explicitly requests them. Prefer scope, dependencies, risks, and observable acceptance criteria.
130
+
84
131
---
85
132
86
-
## Stage 4: Review
133
+
## Review and Execution
87
134
88
-
Before executing, the plan must be self-reviewed:
135
+
Before executing a Level 2 or Level 3 plan, review it at a depth proportionate to risk:
89
136
90
-
- Does this plan cover all edge cases?
137
+
- Does the plan cover relevant edge cases?
91
138
- Is there a simpler approach that achieves the same result?
92
-
- Does this break any existing behavior?
93
-
- Is the scope creep-free? (Only doing what was planned.)
94
-
95
-
---
96
-
97
-
## Stage 5: Execute
139
+
- Does this break existing behavior or compatibility?
140
+
- Is the scope focused on the requested outcome?
141
+
- Is rollback or recovery defined where needed?
98
142
99
-
Only now write code. Follow the plan step by step. Mark steps complete as you go.
143
+
During execution:
100
144
101
-
**During execution:**
102
145
- Make one logical change at a time.
103
-
- Run type checks after each significant change.
146
+
- Run targeted checks after significant changes.
104
147
- Never leave the codebase in a broken state between steps.
105
-
- If you discover something that changes the plan → stop, update the plan, then continue.
148
+
- If a discovery materially changes scope or risk, stop and update the plan before continuing.
106
149
107
150
---
108
151
109
-
## ⛔ What Happens If You Skip This
110
-
111
-
- Broken builds that block others
112
-
- Regressions in features that seemed unrelated
113
-
- Type errors discovered at bundle time, not at dev time
114
-
- Wasted hours debugging avoidable issues
115
-
- Rejected PRs that require full rewrites
152
+
## Verification Is Always Required
116
153
117
-
**The plan takes 10 minutes. The bugs it prevents take hours to fix.**
154
+
The amount of planning varies; honest verification does not. Select checks that prove the requested change without imposing unrelated work. Report what actually ran and do not claim success without evidence.
118
155
119
156
---
120
157
121
-
*This document applies to ALL contributors: human and AI agents alike.*
158
+
*This document applies to all contributors, human and AI agents alike. Last updated: 2026-08-02.*
Copy file name to clipboardExpand all lines: WORKSPACE_GOVERNANCE.md
+19-22Lines changed: 19 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@
8
8
9
9
### 1. NO SHORTCUTS
10
10
- Never use `--no-verify`, `--force`, shallow clones, or any flag that bypasses safety checks unless explicitly documented and approved.
11
-
- Never skip tests, type checks, or linting.
11
+
- Never skip checks that are relevant to the change; choose tests, type checks, linting, and manual verification proportionate to scope and risk.
12
12
- Never comment out failing tests to make CI pass.
13
13
- Never use `any` in TypeScript unless it is the ONLY option and is explicitly justified in a comment.
14
14
- Never hardcode values that belong in config or constants.
@@ -20,9 +20,10 @@
20
20
- Do not fake file counts, hashes, or comparison results.
21
21
- Every claim must be provable. Every action must be verifiable.
22
22
23
-
### 3. PLAN FIRST — ALWAYS
24
-
-**Zero code changes without a written plan.** See `PLANNING_REQUIRED.md`.
25
-
- Every feature, fix, or refactor starts with: Research → Design → Plan → Review → Execute.
23
+
### 3. PLAN IN PROPORTION TO RISK
24
+
- Assess scope, risk, reversibility, and complexity before changing code. See `PLANNING_REQUIRED.md`.
25
+
- Trivial, low-risk changes may use a brief task checklist; substantial or high-risk work requires research, design, an implementation plan, and review.
26
+
- Agent-created plans are canonical in the virtual Spec Workspace. Create repository planning documents only when a maintainer or the task explicitly requires a versioned artifact.
26
27
- No one-line "quick fixes" without understanding the full impact.
27
28
28
29
### 4. NO HALF-WORK
@@ -40,17 +41,15 @@
40
41
41
42
## 📋 PRE-CHANGE CHECKLIST
42
43
43
-
Before making ANY change to this codebase, answer ALL of these:
44
+
Apply each item when relevant to the change's scope and risk:
44
45
45
-
-[ ] Have I read `ARCHITECTURE.md` and understand the affected modules?
46
-
-[ ] Have I read `REQUIREMENTS.md` for the current task scope?
47
-
-[ ] Have I written a plan in `docs/plans/` (from `PLANNING_REQUIRED.md`)?
46
+
-[ ] Have I read the relevant architecture and requirements for the affected modules?
47
+
-[ ] Have I assessed scope, risk, reversibility, and complexity?
48
+
-[ ] If a written plan is warranted, have I created or updated it in the virtual Spec Workspace?
49
+
-[ ] If a repository planning document is explicitly required, have I created it in the requested location?
48
50
-[ ] Have I identified all files that will be affected?
49
51
-[ ] Have I checked for existing tests that cover this area?
50
-
-[ ] Have I verified the change does not break existing functionality?
51
-
-[ ] Have I run `pnpm check-types` before submitting?
52
-
-[ ] Have I run `pnpm test` before submitting?
53
-
-[ ] Have I run `pnpm lint` before submitting?
52
+
-[ ] Have I selected verification proportionate to the change, including type checks, tests, lint, or manual checks as applicable?
54
53
55
54
---
56
55
@@ -100,9 +99,9 @@ apps/
100
99
vscode-e2e/ ← End-to-end tests
101
100
vscode-nightly/ ← Nightly build configuration
102
101
103
-
docs/ ← All planning, research, decisions (our addition)
104
-
plans/ ← Per-task implementation plans
105
-
research/ ← Research notes
102
+
docs/ ← Repository-visible references and durable records
-`integration` — canonical working and integration branch; all ordinary PRs target this branch.
128
+
- Short-lived `feature/<name>`, `fix/<name>`, `refactor/<name>`, or `docs/<name>` branches may be used when isolation or review warrants them; branch from and merge back into `integration`.
129
+
-`main` — stable release branch; do not use it as the ordinary development base or PR target.
133
130
134
-
Never push directly to `main`. Always use a branch + PR.
131
+
Never push directly to `main`. Follow `docs/BRANCH_AND_UPSTREAM_POLICY.md` and ADR-005.
|[`research/`](research/)| One research doc per investigation. |
48
-
|[`plans/`](plans/)| One implementation plan per task. |
49
-
|[`decisions/`](decisions/)| Architecture Decision Records (ADRs). |
45
+
The virtual Spec Workspace is canonical for agent-created requirements, designs, and implementation plans. Repository documents are conditional: create them only when a maintainer or task explicitly requests a versioned artifact, or when an ADR/durable project record is required.
0 commit comments