development-companion 0.0.0-stage → 1.0.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.
- package/LICENSE +21 -0
- package/README.md +229 -2
- package/RELEASE.md +107 -0
- package/adapters/README.md +113 -0
- package/adapters/claude-code/README.md +81 -0
- package/adapters/claude-code/adapter.json +10 -0
- package/adapters/cline/adapter.json +9 -0
- package/adapters/codex/README.md +80 -0
- package/adapters/codex/adapter.json +9 -0
- package/adapters/copilot-cli/adapter.json +9 -0
- package/adapters/cursor/adapter.json +9 -0
- package/adapters/gemini-cli/adapter.json +9 -0
- package/adapters/generic/adapter.json +9 -0
- package/adapters/opencode/README.md +89 -0
- package/adapters/opencode/adapter.json +9 -0
- package/adapters/pi/README.md +83 -0
- package/adapters/pi/adapter.json +9 -0
- package/adapters/windsurf/adapter.json +9 -0
- package/bin/devcomp.mjs +8 -0
- package/core/guidelines/backend.md +103 -0
- package/core/guidelines/collaboration.md +78 -0
- package/core/guidelines/frontend.md +106 -0
- package/core/guidelines/security.md +90 -0
- package/core/guidelines/testing.md +90 -0
- package/core/principles.md +208 -0
- package/core/process.md +224 -0
- package/core/quality-gates.md +192 -0
- package/core/roles/README.md +55 -0
- package/core/roles/architect.md +75 -0
- package/core/roles/backend-engineer.md +74 -0
- package/core/roles/cybersecurity-engineer.md +55 -0
- package/core/roles/desktop-linux-engineer.md +50 -0
- package/core/roles/desktop-macos-engineer.md +50 -0
- package/core/roles/desktop-windows-engineer.md +50 -0
- package/core/roles/frontend-engineer.md +72 -0
- package/core/roles/mobile-engineer.md +50 -0
- package/core/roles/multiplatform-engineer.md +49 -0
- package/core/roles/orchestrator.md +69 -0
- package/core/roles/qa-engineer.md +69 -0
- package/core/roles/reviewer.md +77 -0
- package/core/roles/sre-engineer.md +51 -0
- package/core/roles/team-lead.md +67 -0
- package/core/workflow.md +169 -0
- package/package.json +53 -4
- package/skills/architecture-design/SKILL.md +116 -0
- package/skills/backend-development/SKILL.md +127 -0
- package/skills/code-review/SKILL.md +144 -0
- package/skills/delivery-orchestration/SKILL.md +119 -0
- package/skills/deployment-sre/SKILL.md +111 -0
- package/skills/desktop-development/SKILL.md +51 -0
- package/skills/development-workflow/SKILL.md +158 -0
- package/skills/frontend-development/SKILL.md +136 -0
- package/skills/linux-development/SKILL.md +44 -0
- package/skills/macos-development/SKILL.md +45 -0
- package/skills/mobile-development/SKILL.md +60 -0
- package/skills/multiplatform-development/SKILL.md +45 -0
- package/skills/project-discovery/SKILL.md +122 -0
- package/skills/security-review/SKILL.md +109 -0
- package/skills/test-strategy/SKILL.md +109 -0
- package/skills/ux-design/SKILL.md +108 -0
- package/skills/windows-development/SKILL.md +45 -0
- package/src/args.mjs +42 -0
- package/src/cli.mjs +449 -0
- package/src/content.mjs +72 -0
- package/src/detect.mjs +119 -0
- package/src/install.mjs +186 -0
- package/src/prompt.mjs +35 -0
- package/src/rules.mjs +83 -0
- package/src/scaffold.mjs +433 -0
- package/templates/artifacts/01-operational-brief.md +37 -0
- package/templates/artifacts/02-architecture.md +33 -0
- package/templates/artifacts/03-threat-model.md +29 -0
- package/templates/artifacts/04-test-plan.md +35 -0
- package/templates/artifacts/05-ux-spec.md +31 -0
- package/templates/artifacts/06-delivery-plan.md +29 -0
- package/templates/artifacts/07-security-report.md +25 -0
- package/templates/artifacts/08-qa-report.md +32 -0
- package/templates/artifacts/09-runbook.md +43 -0
- package/templates/artifacts/10-closure.md +25 -0
- package/templates/artifacts/README.md +17 -0
- package/templates/rules/AGENTS.block.md +36 -0
- package/templates/rules/CLAUDE.block.md +3 -0
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Testing Guidelines
|
|
2
|
+
|
|
3
|
+
Tests exist to prove behavior and prevent regressions. They are evidence, not a
|
|
4
|
+
ritual and not a coverage target.
|
|
5
|
+
|
|
6
|
+
## Strategy
|
|
7
|
+
|
|
8
|
+
Use the cheapest test level that can prove the behavior:
|
|
9
|
+
|
|
10
|
+
| Level | Use for | Avoid |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| **Unit** | Pure logic, invariants, edge cases, parsing, calculations | Testing framework wiring or private methods |
|
|
13
|
+
| **Component** | UI behavior, states, keyboard interaction | Snapshot-only assertions |
|
|
14
|
+
| **Integration** | Real database, API contract, module boundaries | Mocking the thing under test |
|
|
15
|
+
| **End-to-end** | Critical user flows, auth, payments, cross-service behavior | Covering every permutation |
|
|
16
|
+
| **Manual** | Visual quality, accessibility, exploratory checks | Replacing automatable regression tests |
|
|
17
|
+
|
|
18
|
+
The shape should follow risk, not a fixed pyramid. A small project may need mostly
|
|
19
|
+
integration tests; a complex domain needs strong unit coverage.
|
|
20
|
+
|
|
21
|
+
## What to test
|
|
22
|
+
|
|
23
|
+
- The acceptance criteria, in observable terms.
|
|
24
|
+
- Boundaries: empty, null, minimum, maximum, malformed, oversized, duplicate.
|
|
25
|
+
- Failure paths: invalid input, denied access, timeout, conflict, partial failure.
|
|
26
|
+
- State transitions: double submit, retry, refresh, stale cache, rollback.
|
|
27
|
+
- Contracts: request/response shape, status codes, error codes, events.
|
|
28
|
+
- Regressions: every fixed bug gets a test that fails without the fix.
|
|
29
|
+
- Accessibility: keyboard operation and accessible names for key flows.
|
|
30
|
+
- Performance: only where a budget or regression risk is real.
|
|
31
|
+
|
|
32
|
+
## What not to test
|
|
33
|
+
|
|
34
|
+
- Private implementation details that are free to change.
|
|
35
|
+
- Framework behavior you did not write.
|
|
36
|
+
- Exact log strings or CSS classes unless they are part of the contract.
|
|
37
|
+
- Mocks asserting that a mock was called, with no observable outcome.
|
|
38
|
+
- Every permutation of a combinatorial space; choose representative cases.
|
|
39
|
+
|
|
40
|
+
## Bug fixes
|
|
41
|
+
|
|
42
|
+
1. Reproduce the bug with a failing test.
|
|
43
|
+
2. Confirm the test fails for the right reason.
|
|
44
|
+
3. Fix the root cause.
|
|
45
|
+
4. Confirm the test passes and the rest of the suite still passes.
|
|
46
|
+
5. Add adjacent cases if the same defect could exist elsewhere.
|
|
47
|
+
|
|
48
|
+
If a failing test is impossible, document the manual reproduction and why automation
|
|
49
|
+
is not feasible.
|
|
50
|
+
|
|
51
|
+
## Determinism
|
|
52
|
+
|
|
53
|
+
- Control time, randomness, network, and external services.
|
|
54
|
+
- Isolate test data; do not depend on execution order or shared mutable state.
|
|
55
|
+
- Avoid sleeps. Wait for a condition or use fake timers.
|
|
56
|
+
- Make retries explicit and bounded; do not hide flakiness.
|
|
57
|
+
- Treat a flaky test as a defect, not as noise.
|
|
58
|
+
|
|
59
|
+
## Test data
|
|
60
|
+
|
|
61
|
+
- Use builders or factories with sensible defaults and explicit overrides.
|
|
62
|
+
- Keep fixtures small and readable; a test should show the relevant data inline.
|
|
63
|
+
- Never use production personal data.
|
|
64
|
+
- Use realistic values for formats, time zones, encodings, and money.
|
|
65
|
+
|
|
66
|
+
## Coverage
|
|
67
|
+
|
|
68
|
+
- Coverage is a signal for untested areas, not a goal by itself.
|
|
69
|
+
- Do not chase 100%; cover risk and contracts.
|
|
70
|
+
- A high-coverage suite that asserts nothing useful is worse than a small, meaningful
|
|
71
|
+
suite.
|
|
72
|
+
- Review uncovered branches in critical code.
|
|
73
|
+
|
|
74
|
+
## CI and local checks
|
|
75
|
+
|
|
76
|
+
- Run the fastest checks first: typecheck, lint, unit.
|
|
77
|
+
- Run integration/e2e where the environment supports them.
|
|
78
|
+
- Fail the build on test failures, not on warnings you have decided to ignore.
|
|
79
|
+
- Keep a documented command to run the full suite locally.
|
|
80
|
+
- Report skipped checks explicitly.
|
|
81
|
+
|
|
82
|
+
## Anti-patterns
|
|
83
|
+
|
|
84
|
+
- Testing the mock instead of the behavior.
|
|
85
|
+
- Snapshot tests for dynamic UI with no semantic assertions.
|
|
86
|
+
- One giant end-to-end test that duplicates unit coverage.
|
|
87
|
+
- Sleep-based synchronization.
|
|
88
|
+
- Shared database state between tests.
|
|
89
|
+
- Asserting implementation details that make refactors painful.
|
|
90
|
+
- Adding a test after the fact that would pass even with the bug.
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
# Engineering Principles
|
|
2
|
+
|
|
3
|
+
These principles are the non-negotiable base for every role, skill, and adapter.
|
|
4
|
+
They are deliberately harness-neutral: they apply whether the work is done by
|
|
5
|
+
OpenCode, Claude Code, Codex, Pi, or a human.
|
|
6
|
+
|
|
7
|
+
## The prime directive
|
|
8
|
+
|
|
9
|
+
**Leave the system working and verifiably better than you found it.**
|
|
10
|
+
|
|
11
|
+
"Better" means the requested problem is solved, the change is understandable,
|
|
12
|
+
and the evidence shows it works. Clever code that cannot be verified is not better.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. Understand before changing
|
|
17
|
+
|
|
18
|
+
Read the relevant code, trace the real execution path, and check existing
|
|
19
|
+
conventions before proposing a change. A plausible guess is not understanding.
|
|
20
|
+
|
|
21
|
+
**In practice:** find the entry point, the data flow, the tests, and the closest
|
|
22
|
+
existing example. State assumptions explicitly when you cannot confirm them.
|
|
23
|
+
|
|
24
|
+
**Red flags:** editing from filenames alone; inventing APIs; ignoring local
|
|
25
|
+
patterns; "it probably works".
|
|
26
|
+
|
|
27
|
+
## 2. Solve the problem, not the symptom
|
|
28
|
+
|
|
29
|
+
Fix the cause, not the error message. A workaround is acceptable only when it is
|
|
30
|
+
explicit, bounded, and documented as debt.
|
|
31
|
+
|
|
32
|
+
**In practice:** reproduce the failure, identify the failing invariant, and add a
|
|
33
|
+
regression test that would have caught it.
|
|
34
|
+
|
|
35
|
+
**Red flags:** swallowing exceptions; adding sleeps; disabling checks; special-casing
|
|
36
|
+
test data.
|
|
37
|
+
|
|
38
|
+
## 3. Make the smallest coherent change
|
|
39
|
+
|
|
40
|
+
Prefer the smallest diff that fully solves the problem. Small changes are easier to
|
|
41
|
+
review, test, revert, and reason about.
|
|
42
|
+
|
|
43
|
+
**In practice:** keep unrelated refactors out. If a larger change is genuinely
|
|
44
|
+
required, explain why and split it into reviewable steps.
|
|
45
|
+
|
|
46
|
+
**Red flags:** drive-by renames; mass formatting; "while I was here" changes;
|
|
47
|
+
rewriting a module to fix a one-line bug.
|
|
48
|
+
|
|
49
|
+
## 4. Contracts are promises
|
|
50
|
+
|
|
51
|
+
APIs, component props, database schemas, events, file formats, and public types are
|
|
52
|
+
contracts. Changing them affects callers you may not see.
|
|
53
|
+
|
|
54
|
+
**In practice:** search all call sites, update consumers, preserve backward
|
|
55
|
+
compatibility where required, and document breaking changes.
|
|
56
|
+
|
|
57
|
+
**Red flags:** changing a response shape without checking clients; nullable fields
|
|
58
|
+
becoming required; silent semantic changes.
|
|
59
|
+
|
|
60
|
+
## 5. Validate at the boundary; trust nothing
|
|
61
|
+
|
|
62
|
+
All external input is untrusted: HTTP requests, user input, files, environment
|
|
63
|
+
variables, third-party APIs, and model output.
|
|
64
|
+
|
|
65
|
+
**In practice:** validate shape, type, range, size, and encoding at the edge.
|
|
66
|
+
Reject unknown or malformed input with a clear error. Keep validation close to the
|
|
67
|
+
boundary, not scattered through the domain.
|
|
68
|
+
|
|
69
|
+
**Red flags:** trusting client-side checks; parsing without limits; passing raw
|
|
70
|
+
input into queries, templates, shells, or file paths.
|
|
71
|
+
|
|
72
|
+
## 6. Make invalid states unrepresentable
|
|
73
|
+
|
|
74
|
+
Prefer types, schemas, and invariants that prevent bad states instead of relying on
|
|
75
|
+
comments or vigilance.
|
|
76
|
+
|
|
77
|
+
**In practice:** use discriminated unions, enums, branded types, database
|
|
78
|
+
constraints, and constructors that enforce invariants. Validate once, then work with
|
|
79
|
+
a trusted type.
|
|
80
|
+
|
|
81
|
+
**Red flags:** boolean soup; optional fields that must always be present together;
|
|
82
|
+
"remember to check X" comments.
|
|
83
|
+
|
|
84
|
+
## 7. Security and privacy are defaults
|
|
85
|
+
|
|
86
|
+
Every feature has a threat model, even a small one. Authentication, authorization,
|
|
87
|
+
data exposure, injection, and secrets are part of the design, not a final checklist.
|
|
88
|
+
|
|
89
|
+
**In practice:** deny by default; authorize per resource; minimize collected data;
|
|
90
|
+
keep secrets server-side; encode output; log without PII. See
|
|
91
|
+
`core/guidelines/security.md`.
|
|
92
|
+
|
|
93
|
+
**Red flags:** "we'll add auth later"; secrets in client code or logs; authorization
|
|
94
|
+
checks only in the UI; unbounded file uploads.
|
|
95
|
+
|
|
96
|
+
## 8. Accessibility and performance are functional requirements
|
|
97
|
+
|
|
98
|
+
A fast, accessible interface is part of correctness. An inaccessible feature is a
|
|
99
|
+
broken feature for real users.
|
|
100
|
+
|
|
101
|
+
**In practice:** semantic HTML, keyboard access, visible focus, labels, contrast,
|
|
102
|
+
reduced motion, responsive layouts, and loading/error/empty states. Measure
|
|
103
|
+
performance against a budget instead of guessing.
|
|
104
|
+
|
|
105
|
+
**Red flags:** div buttons; placeholder-only labels; horizontal scroll on mobile;
|
|
106
|
+
unbounded lists; layouts that shift after load.
|
|
107
|
+
|
|
108
|
+
## 9. Tests are evidence, not decoration
|
|
109
|
+
|
|
110
|
+
Tests exist to prove behavior and prevent regressions. A test that never fails is
|
|
111
|
+
not evidence.
|
|
112
|
+
|
|
113
|
+
**In practice:** test behavior and contracts, not private implementation details.
|
|
114
|
+
For a bug fix, write a failing test first. For a refactor, prove behavior is
|
|
115
|
+
unchanged.
|
|
116
|
+
|
|
117
|
+
**Red flags:** snapshot-only coverage; tests that assert the mock; skipped tests
|
|
118
|
+
without a reason; coverage as the only goal.
|
|
119
|
+
|
|
120
|
+
## 10. Reversible by design
|
|
121
|
+
|
|
122
|
+
Prefer changes that can be rolled back or migrated safely. Irreversible operations
|
|
123
|
+
need explicit approval and a recovery plan.
|
|
124
|
+
|
|
125
|
+
**In practice:** use expand/contract migrations, feature flags for risky behavior,
|
|
126
|
+
idempotent jobs, and backups before destructive operations.
|
|
127
|
+
|
|
128
|
+
**Red flags:** dropping columns in the same release that stops using them; no
|
|
129
|
+
rollback path; one-way data transformations.
|
|
130
|
+
|
|
131
|
+
## 11. Observe what you ship
|
|
132
|
+
|
|
133
|
+
If it can fail in production, you need to know. Logs, metrics, and traces are part
|
|
134
|
+
of the feature, not an operations afterthought.
|
|
135
|
+
|
|
136
|
+
**In practice:** structured logs with correlation IDs, meaningful error messages,
|
|
137
|
+
health checks, and metrics for the failure modes that matter. Never log secrets or
|
|
138
|
+
PII.
|
|
139
|
+
|
|
140
|
+
**Red flags:** silent failures; generic "something went wrong"; no way to trace a
|
|
141
|
+
request; logging entire payloads.
|
|
142
|
+
|
|
143
|
+
## 12. Communicate uncertainty and decisions
|
|
144
|
+
|
|
145
|
+
State what you know, what you assume, and what you could not verify. Hidden
|
|
146
|
+
uncertainty becomes someone else's incident.
|
|
147
|
+
|
|
148
|
+
**In practice:** report evidence, open questions, and residual risk. Record
|
|
149
|
+
architectural decisions with context and consequences. Ask before making a
|
|
150
|
+
high-impact choice on the user's behalf.
|
|
151
|
+
|
|
152
|
+
**Red flags:** confident claims without checks; silent scope changes; decisions
|
|
153
|
+
buried in chat instead of documented.
|
|
154
|
+
|
|
155
|
+
## 13. Evidence over claims
|
|
156
|
+
|
|
157
|
+
A change is not done because it is described as done. It is done when a check, test,
|
|
158
|
+
request, screenshot, CVE, or metric proves it.
|
|
159
|
+
|
|
160
|
+
**In practice:** report the command and its result; attach the failing request or the
|
|
161
|
+
screenshot; state what could not be verified.
|
|
162
|
+
|
|
163
|
+
**Red flags:** "should work"; "tests pass" without output; a finding without reproduction;
|
|
164
|
+
a completion report that summarizes intention instead of evidence.
|
|
165
|
+
|
|
166
|
+
## 14. Environment variables: names, not values
|
|
167
|
+
|
|
168
|
+
Agents may need to know whether a variable is configured. They never need its value.
|
|
169
|
+
|
|
170
|
+
**In practice:** read key names from `.env.example`; check presence with
|
|
171
|
+
`test -n "$VAR"` and print only set/unset; redact logs. The CLI never opens `.env`.
|
|
172
|
+
|
|
173
|
+
**Red flags:** `cat .env`; `env`; `printenv` without a name; tokens in logs, screenshots,
|
|
174
|
+
or reports.
|
|
175
|
+
|
|
176
|
+
## 15. The domain is independent; patterns need a reason
|
|
177
|
+
|
|
178
|
+
Business rules must survive a change of framework, database, vendor, or delivery
|
|
179
|
+
mechanism. Architecture exists to protect that independence.
|
|
180
|
+
|
|
181
|
+
**In practice:** keep `domain` free of framework and infrastructure imports; define ports
|
|
182
|
+
owned by the inside; implement adapters outside; record non-obvious patterns in an ADR.
|
|
183
|
+
|
|
184
|
+
**Red flags:** ORM entities as domain models; HTTP types in use cases; a pattern applied
|
|
185
|
+
"because it is best practice" with no problem to solve.
|
|
186
|
+
|
|
187
|
+
## 16. Design documents are local by default; memory is optional
|
|
188
|
+
|
|
189
|
+
The repository should stay focused on code. Design decisions, evidence, and reports belong
|
|
190
|
+
in `.companion/local/`, which is ignored by git; tracking them is an explicit opt-in.
|
|
191
|
+
Engram can index them, but the files remain the source of truth.
|
|
192
|
+
|
|
193
|
+
**In practice:** write discovery, architecture, test plans, and reports locally; use
|
|
194
|
+
`--track-docs` when the team wants them versioned; save durable decisions to memory when
|
|
195
|
+
available.
|
|
196
|
+
|
|
197
|
+
**Red flags:** committing local design notes by accident; treating a memory entry as the
|
|
198
|
+
only record; losing a decision because it lived only in chat.
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## How to use these principles
|
|
203
|
+
|
|
204
|
+
- When principles conflict, prioritize **correctness and safety** over speed, and
|
|
205
|
+
**reversibility** over elegance.
|
|
206
|
+
- When a principle cannot be followed, say so explicitly and explain the trade-off.
|
|
207
|
+
- When adding a new rule, ask: does it change behavior, or only restate these
|
|
208
|
+
principles? If it only restates them, do not add it.
|
package/core/process.md
ADDED
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
# Development Process
|
|
2
|
+
|
|
3
|
+
This is the default process for a new project or a major change. It scales down for small
|
|
4
|
+
changes; see `core/workflow.md`.
|
|
5
|
+
|
|
6
|
+
The process is owned by the **Team Lead**. Each phase has an artifact in
|
|
7
|
+
`.companion/local/` and a gate that requires evidence.
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
0 Bootstrap
|
|
11
|
+
→ 1 Operational discovery
|
|
12
|
+
→ 2 Architecture + security (in parallel)
|
|
13
|
+
→ 3 Test strategy
|
|
14
|
+
→ 4 UX/UI
|
|
15
|
+
→ 5 Delivery plan
|
|
16
|
+
→ 6 Implementation
|
|
17
|
+
→ 7 Security verification
|
|
18
|
+
→ 8 QA verification
|
|
19
|
+
→ 9 Deployment
|
|
20
|
+
→ 10 Closure
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Phase 0 — Bootstrap
|
|
24
|
+
|
|
25
|
+
**Owner:** CLI.
|
|
26
|
+
|
|
27
|
+
- Detect the repository, harness, package manager, profile, and branch convention.
|
|
28
|
+
- Install `AGENTS.md` and `CLAUDE.md` using keep, append, or replace.
|
|
29
|
+
- Install process skills, roles, and native bindings.
|
|
30
|
+
- Write `.companion/config.json` and ignore `.companion/local/`.
|
|
31
|
+
|
|
32
|
+
**Gate:** `devcomp doctor` passes; existing rules were not lost.
|
|
33
|
+
|
|
34
|
+
## Phase 1 — Operational discovery
|
|
35
|
+
|
|
36
|
+
**Owner:** Team Lead. **Participant:** the user.
|
|
37
|
+
|
|
38
|
+
Ask, one topic at a time:
|
|
39
|
+
|
|
40
|
+
- What problem, for whom, and why now?
|
|
41
|
+
- What does success look like, and how is it measured?
|
|
42
|
+
- What is in scope and out of scope for the first release?
|
|
43
|
+
- Are there existing repositories, prototypes, designs, or documents?
|
|
44
|
+
- Where will it run: on-prem, VPS, Dokploy, Coolify, cloud?
|
|
45
|
+
- Which third-party services, APIs, MCPs, or on-device capabilities are required?
|
|
46
|
+
- What data is stored, where, and for how long?
|
|
47
|
+
- What authentication is needed: local, OIDC, Firebase, other?
|
|
48
|
+
- Which platforms are targets?
|
|
49
|
+
- What are the deadline, team, budget, and maintenance constraints?
|
|
50
|
+
- Which branch convention is used: gitflow, GitLab flow, trunk-based, GitHub flow, custom?
|
|
51
|
+
Detect it, then ask the user to confirm.
|
|
52
|
+
- What does "done" mean?
|
|
53
|
+
|
|
54
|
+
**Artifact:** `.companion/local/01-operational-brief.md`.
|
|
55
|
+
|
|
56
|
+
**Gate:** the user confirms the brief; no blocking operational question remains.
|
|
57
|
+
|
|
58
|
+
## Phase 2 — Architecture and security
|
|
59
|
+
|
|
60
|
+
**Owner:** Architect. **Participant:** Cybersecurity Engineer, in parallel.
|
|
61
|
+
|
|
62
|
+
Technical questions:
|
|
63
|
+
|
|
64
|
+
- Stack and versions: verify the latest stable release.
|
|
65
|
+
- Monorepo or single repo? Which workspace tool?
|
|
66
|
+
- Monolith, modular monolith, or microservices? Why?
|
|
67
|
+
- Layered, hexagonal, or tactical DDD?
|
|
68
|
+
- Data stores, schema, migrations.
|
|
69
|
+
- AuthN/AuthZ, tenancy, secrets.
|
|
70
|
+
- Integrations, queues, events, webhooks, idempotency.
|
|
71
|
+
- Deployment, observability, backups, rollback.
|
|
72
|
+
- Performance budget and expected load.
|
|
73
|
+
|
|
74
|
+
Security, in parallel:
|
|
75
|
+
|
|
76
|
+
- Assets, actors, entry points, trust boundaries.
|
|
77
|
+
- Threat model and top risks.
|
|
78
|
+
- Controls and accepted risks.
|
|
79
|
+
- Relevant CVEs and supply-chain concerns.
|
|
80
|
+
|
|
81
|
+
**Artifacts:** `.companion/local/02-architecture.md`,
|
|
82
|
+
`.companion/local/03-threat-model.md`, and `adr/NNN-*.md`.
|
|
83
|
+
|
|
84
|
+
**Gate:** stack and versions approved; boundaries and patterns recorded; threats have a
|
|
85
|
+
control or an explicit acceptance; no architecture blocker remains.
|
|
86
|
+
|
|
87
|
+
## Phase 3 — Test strategy
|
|
88
|
+
|
|
89
|
+
**Owner:** QA Engineer. **Participants:** Team Lead, Architect.
|
|
90
|
+
|
|
91
|
+
- Golden paths, dark paths, and edge cases.
|
|
92
|
+
- Test levels and tools.
|
|
93
|
+
- Data, fixtures, and environments.
|
|
94
|
+
- Load/stress scenario, budgets, and target environment.
|
|
95
|
+
- Accessibility, visual, and cross-platform checks.
|
|
96
|
+
- Security checks.
|
|
97
|
+
- Evidence format and exit criteria.
|
|
98
|
+
|
|
99
|
+
**Artifact:** `.companion/local/04-test-plan.md`.
|
|
100
|
+
|
|
101
|
+
**Gate:** every acceptance criterion maps to a test; critical failure paths are covered
|
|
102
|
+
or explicitly accepted.
|
|
103
|
+
|
|
104
|
+
## Phase 4 — UX/UI
|
|
105
|
+
|
|
106
|
+
**Owner:** Frontend Engineer. **Participants:** the user, QA.
|
|
107
|
+
|
|
108
|
+
- Flows and information architecture.
|
|
109
|
+
- Wireframes or mockups in `.companion/local/mockups/`.
|
|
110
|
+
- States: loading, empty, error, unauthorized, offline, retry, success.
|
|
111
|
+
- Responsive breakpoints and behavior.
|
|
112
|
+
- Accessibility: keyboard, focus, labels, contrast, reduced motion.
|
|
113
|
+
- Motion with purpose.
|
|
114
|
+
- Design tokens and components.
|
|
115
|
+
- Screenshots at desktop and mobile widths.
|
|
116
|
+
|
|
117
|
+
**Artifact:** `.companion/local/05-ux-spec.md` plus mockups and screenshots.
|
|
118
|
+
|
|
119
|
+
**Gate:** the user approves the design; states and accessibility are covered.
|
|
120
|
+
|
|
121
|
+
## Phase 5 — Delivery plan
|
|
122
|
+
|
|
123
|
+
**Owner:** Team Lead. **Participants:** all specialists.
|
|
124
|
+
|
|
125
|
+
- Deliverables with owners.
|
|
126
|
+
- Dependencies and critical path.
|
|
127
|
+
- Parallel vs serial work.
|
|
128
|
+
- Branch and release flow.
|
|
129
|
+
- Gates and evidence.
|
|
130
|
+
- Risks and mitigations.
|
|
131
|
+
|
|
132
|
+
**Artifact:** `.companion/local/06-delivery-plan.md`.
|
|
133
|
+
|
|
134
|
+
**Gate:** every task has an owner, an output, and a verification; no two writers own the
|
|
135
|
+
same files.
|
|
136
|
+
|
|
137
|
+
## Phase 6 — Implementation
|
|
138
|
+
|
|
139
|
+
**Owner:** specialists. **Coordinator:** Team Lead.
|
|
140
|
+
|
|
141
|
+
- Contracts and schemas first.
|
|
142
|
+
- Tests alongside behavior; TDD if the project chose it.
|
|
143
|
+
- Small, reversible changes.
|
|
144
|
+
- Domain independent from infrastructure.
|
|
145
|
+
- No secrets, debug output, or dead code.
|
|
146
|
+
- Update ADRs when reality contradicts the plan.
|
|
147
|
+
- Self-review before requesting verification.
|
|
148
|
+
|
|
149
|
+
**Gate:** local checks pass; the diff is scoped; tests cover the new behavior.
|
|
150
|
+
|
|
151
|
+
## Phase 7 — Security verification
|
|
152
|
+
|
|
153
|
+
**Owner:** Cybersecurity Engineer. **Participant:** implementers.
|
|
154
|
+
|
|
155
|
+
- Update the threat model.
|
|
156
|
+
- OWASP ASVS as a reference, not a checklist ritual.
|
|
157
|
+
- SAST, dependency audit, secret scanning, container/configuration scanning.
|
|
158
|
+
- Test authn, authz, sessions, uploads, payments, webhooks, rate limits.
|
|
159
|
+
- Report every finding with reproducible evidence.
|
|
160
|
+
- Re-test fixes.
|
|
161
|
+
|
|
162
|
+
**Artifact:** `.companion/local/07-security-report.md`.
|
|
163
|
+
|
|
164
|
+
**Gate:** no open critical or high findings; medium risks have an owner and a date.
|
|
165
|
+
|
|
166
|
+
## Phase 8 — QA verification
|
|
167
|
+
|
|
168
|
+
**Owner:** QA Engineer. **Participant:** implementers.
|
|
169
|
+
|
|
170
|
+
- Functional and regression tests.
|
|
171
|
+
- Golden/dark paths and edge cases.
|
|
172
|
+
- Load/stress evidence in a target-like environment.
|
|
173
|
+
- Accessibility and visual review against the mockup.
|
|
174
|
+
- Cross-platform and responsive checks.
|
|
175
|
+
- Every failure with reproduction and evidence; fixes are re-verified.
|
|
176
|
+
|
|
177
|
+
**Artifact:** `.companion/local/08-qa-report.md`.
|
|
178
|
+
|
|
179
|
+
**Gate:** must-pass checks are green; known failures are documented; performance is within
|
|
180
|
+
budget or explicitly accepted.
|
|
181
|
+
|
|
182
|
+
## Phase 9 — Deployment
|
|
183
|
+
|
|
184
|
+
**Owner:** SRE Engineer. **Participants:** Team Lead, Cybersecurity.
|
|
185
|
+
|
|
186
|
+
- Docker/compose baseline; VPS with Dokploy or Coolify; cloud reference provider.
|
|
187
|
+
- Secrets in the target manager; never in the repository.
|
|
188
|
+
- Migrations with a tested rollback.
|
|
189
|
+
- Healthchecks, logs, metrics, traces, alerts.
|
|
190
|
+
- Smoke tests against the real target.
|
|
191
|
+
- Performance evidence in the target environment.
|
|
192
|
+
|
|
193
|
+
**Artifact:** `.companion/local/09-runbook.md`.
|
|
194
|
+
|
|
195
|
+
**Gate:** smoke tests pass; rollback is tested; secrets are outside the repo; monitoring is
|
|
196
|
+
active.
|
|
197
|
+
|
|
198
|
+
## Phase 10 — Closure
|
|
199
|
+
|
|
200
|
+
**Owner:** Team Lead. **Participants:** all.
|
|
201
|
+
|
|
202
|
+
- What was delivered and why.
|
|
203
|
+
- Evidence per gate.
|
|
204
|
+
- Residual risks and accepted debt.
|
|
205
|
+
- Runbook and handoff.
|
|
206
|
+
- Next steps.
|
|
207
|
+
|
|
208
|
+
**Artifact:** `.companion/local/10-closure.md`.
|
|
209
|
+
|
|
210
|
+
**Gate:** the user accepts; no claim of "done" lacks evidence; the repository is consistent.
|
|
211
|
+
|
|
212
|
+
## Scaling down
|
|
213
|
+
|
|
214
|
+
| Change | Process |
|
|
215
|
+
|---|---|
|
|
216
|
+
| Typo, docs, one-line fix | Recon → change → check → report |
|
|
217
|
+
| Feature in one layer | Brief → plan → implement → tests → self-review |
|
|
218
|
+
| Cross-layer, data, auth, public contract | Full process + independent security and QA |
|
|
219
|
+
| Incident | Stabilize → diagnose → fix → regression test → short postmortem |
|
|
220
|
+
|
|
221
|
+
## Evidence
|
|
222
|
+
|
|
223
|
+
A gate is not closed by a narrative. It is closed by a command and its output, a test, a
|
|
224
|
+
request, a screenshot, a CVE, or a metric. See `core/quality-gates.md`.
|