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,192 @@
|
|
|
1
|
+
# Quality Gates
|
|
2
|
+
|
|
3
|
+
A quality gate is a condition that must be true before a change can be considered
|
|
4
|
+
complete. Gates are evidence-based: "I ran it and it passed" beats "it should work".
|
|
5
|
+
|
|
6
|
+
## Universal gates
|
|
7
|
+
|
|
8
|
+
Every change, regardless of type:
|
|
9
|
+
|
|
10
|
+
- [ ] The requested behavior or documentation is complete.
|
|
11
|
+
- [ ] The diff is scoped; unrelated changes are excluded.
|
|
12
|
+
- [ ] The diff has been read end-to-end by the author.
|
|
13
|
+
- [ ] No secrets, tokens, credentials, or private data are added.
|
|
14
|
+
- [ ] No debug output, commented-out code, or temporary files remain.
|
|
15
|
+
- [ ] Relevant checks pass, or the reason they could not run is stated.
|
|
16
|
+
- [ ] New behavior has tests or a documented manual verification.
|
|
17
|
+
- [ ] Docs, comments, and examples are not stale.
|
|
18
|
+
- [ ] Public contracts and their consumers are consistent.
|
|
19
|
+
- [ ] Residual risks are reported honestly.
|
|
20
|
+
|
|
21
|
+
## Gates by change type
|
|
22
|
+
|
|
23
|
+
### Bug fix
|
|
24
|
+
|
|
25
|
+
- [ ] The failure was reproduced before the fix.
|
|
26
|
+
- [ ] A test fails without the fix and passes with it (regression test).
|
|
27
|
+
- [ ] The root cause is addressed, not only the symptom.
|
|
28
|
+
- [ ] Related code paths were checked for the same defect.
|
|
29
|
+
- [ ] The fix does not weaken validation, logging, or error handling.
|
|
30
|
+
|
|
31
|
+
### Feature
|
|
32
|
+
|
|
33
|
+
- [ ] Acceptance criteria are observable and covered.
|
|
34
|
+
- [ ] Loading, empty, error, unauthorized, and retry states are handled where relevant.
|
|
35
|
+
- [ ] Input is validated at the boundary.
|
|
36
|
+
- [ ] Authorization is enforced server-side, not only in the UI.
|
|
37
|
+
- [ ] Tests cover the happy path and the important failure paths.
|
|
38
|
+
- [ ] Observability exists for new failure modes.
|
|
39
|
+
- [ ] Documentation is updated.
|
|
40
|
+
|
|
41
|
+
### Refactor
|
|
42
|
+
|
|
43
|
+
- [ ] Behavior is unchanged by definition and by tests.
|
|
44
|
+
- [ ] Baseline tests passed before the refactor.
|
|
45
|
+
- [ ] Changes are small and reversible; no feature work is mixed in.
|
|
46
|
+
- [ ] Public contracts are preserved, or the change is explicitly a breaking change.
|
|
47
|
+
- [ ] Performance did not regress in a measurable way.
|
|
48
|
+
|
|
49
|
+
### Frontend
|
|
50
|
+
|
|
51
|
+
- [ ] Typecheck and lint pass.
|
|
52
|
+
- [ ] Component/unit tests cover behavior, not implementation details.
|
|
53
|
+
- [ ] Keyboard navigation works; focus is visible and managed.
|
|
54
|
+
- [ ] Semantic HTML and accessible names are present.
|
|
55
|
+
- [ ] Responsive behavior is checked at meaningful breakpoints.
|
|
56
|
+
- [ ] Loading, empty, error, and disabled states exist.
|
|
57
|
+
- [ ] Images, fonts, and code splitting respect the performance budget.
|
|
58
|
+
- [ ] No secrets or sensitive data are shipped to the client.
|
|
59
|
+
|
|
60
|
+
### Backend
|
|
61
|
+
|
|
62
|
+
- [ ] API/contract changes are reflected in consumers and docs.
|
|
63
|
+
- [ ] Input validation covers shape, type, range, size, and encoding.
|
|
64
|
+
- [ ] Authentication and per-resource authorization are enforced.
|
|
65
|
+
- [ ] Database changes use a reversible migration strategy.
|
|
66
|
+
- [ ] Transactions and constraints protect invariants.
|
|
67
|
+
- [ ] Retries, timeouts, and idempotency are handled where relevant.
|
|
68
|
+
- [ ] Integration tests use a realistic database or service.
|
|
69
|
+
- [ ] Logs and metrics cover the new failure modes without PII.
|
|
70
|
+
|
|
71
|
+
### Documentation
|
|
72
|
+
|
|
73
|
+
- [ ] Commands are copy-pasteable and were run.
|
|
74
|
+
- [ ] Links resolve.
|
|
75
|
+
- [ ] Examples match the current API and file layout.
|
|
76
|
+
- [ ] The document says who it is for and when to use it.
|
|
77
|
+
- [ ] No claims about behavior that the code does not support.
|
|
78
|
+
|
|
79
|
+
### Release / operations
|
|
80
|
+
|
|
81
|
+
- [ ] Changelog and version are updated.
|
|
82
|
+
- [ ] Rollback or roll-forward plan exists.
|
|
83
|
+
- [ ] Destructive operations have a backup and explicit approval.
|
|
84
|
+
- [ ] Monitoring and alerts cover the release.
|
|
85
|
+
- [ ] The release was verified in an environment that resembles production.
|
|
86
|
+
|
|
87
|
+
## Process gates
|
|
88
|
+
|
|
89
|
+
For a new project or a major change, each phase in `core/process.md` has a gate:
|
|
90
|
+
|
|
91
|
+
| Phase | Gate evidence |
|
|
92
|
+
|---|---|
|
|
93
|
+
| Discovery | The user confirmed the operational brief; no blocking question. |
|
|
94
|
+
| Architecture | Approved stack and versions, boundaries, ADRs, threat model. |
|
|
95
|
+
| Test strategy | Every acceptance criterion maps to a test; failure paths covered. |
|
|
96
|
+
| UX | Approved flows, states, screenshots, and accessibility checklist. |
|
|
97
|
+
| Delivery plan | Owners, dependencies, gates, and branch convention recorded. |
|
|
98
|
+
| Implementation | Local checks pass; diff scoped; new behavior tested. |
|
|
99
|
+
| Security | No open critical/high findings; evidence per finding. |
|
|
100
|
+
| QA | Must-pass checks green; load/a11y/visual evidence; known failures documented. |
|
|
101
|
+
| Deployment | Smoke test in target; rollback tested; secrets outside repo. |
|
|
102
|
+
| Closure | Evidence per gate; residual risks and handoff written. |
|
|
103
|
+
|
|
104
|
+
## Security and secrets
|
|
105
|
+
|
|
106
|
+
- [ ] No `.env` values were read, printed, or committed.
|
|
107
|
+
- [ ] Secret scanning ran (gitleaks or equivalent).
|
|
108
|
+
- [ ] Dependencies were audited and the lockfile is current.
|
|
109
|
+
- [ ] Authorization is enforced server-side and tested with more than one role.
|
|
110
|
+
- [ ] Findings include reproducible evidence, not a suspicion.
|
|
111
|
+
- [ ] Logs, screenshots, reports, and crash dumps contain no secrets or PII.
|
|
112
|
+
|
|
113
|
+
## Mobile and desktop
|
|
114
|
+
|
|
115
|
+
- [ ] The app was tested on a real device or clean VM, not only an emulator.
|
|
116
|
+
- [ ] Permissions and sandbox entitlements are minimal and explained.
|
|
117
|
+
- [ ] Install, update, rollback, and uninstall were exercised.
|
|
118
|
+
- [ ] Accessibility and keyboard navigation were verified.
|
|
119
|
+
- [ ] Signing and notarization/signing checks pass.
|
|
120
|
+
- [ ] Performance was measured on a low-end reference target.
|
|
121
|
+
|
|
122
|
+
## Package release
|
|
123
|
+
|
|
124
|
+
- [ ] Version and changelog are updated.
|
|
125
|
+
- [ ] The published file list contains only intended files.
|
|
126
|
+
- [ ] `npm pack --dry-run` was inspected.
|
|
127
|
+
- [ ] The package installs and runs from a clean directory.
|
|
128
|
+
- [ ] No `postinstall`, telemetry, or secret read was added.
|
|
129
|
+
- [ ] The release was verified with `init` and `doctor` on a clean repo.
|
|
130
|
+
|
|
131
|
+
## Finding format
|
|
132
|
+
|
|
133
|
+
```text
|
|
134
|
+
Finding:
|
|
135
|
+
Severity: critical | high | medium | low
|
|
136
|
+
Evidence: file:line + snippet | request/response | CVE | screenshot
|
|
137
|
+
Impact:
|
|
138
|
+
Fix:
|
|
139
|
+
Verification:
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Evidence ladder
|
|
143
|
+
|
|
144
|
+
Prefer higher levels:
|
|
145
|
+
|
|
146
|
+
1. **Claim** — "it should work" (not evidence).
|
|
147
|
+
2. **Static** — typecheck, lint, schema validation.
|
|
148
|
+
3. **Unit** — isolated behavior and edge cases.
|
|
149
|
+
4. **Integration** — real boundaries and contracts.
|
|
150
|
+
5. **End-to-end** — the actual user or system flow.
|
|
151
|
+
6. **Artifact** — request/response, screenshot, CVE reproduction, load metric.
|
|
152
|
+
7. **Production observation** — metrics, logs, canary results.
|
|
153
|
+
|
|
154
|
+
State the level you reached. Do not present a lower level as a higher one.
|
|
155
|
+
|
|
156
|
+
## Completion report
|
|
157
|
+
|
|
158
|
+
Use this format at the end of a task:
|
|
159
|
+
|
|
160
|
+
```markdown
|
|
161
|
+
## Delivered
|
|
162
|
+
- Concise description of what changed and why.
|
|
163
|
+
|
|
164
|
+
## Verification
|
|
165
|
+
- `command` → passed / failed / not run (reason)
|
|
166
|
+
- Manual check → what was observed
|
|
167
|
+
|
|
168
|
+
## Risks and not covered
|
|
169
|
+
- Residual risk, skipped checks, assumptions, follow-ups.
|
|
170
|
+
|
|
171
|
+
## Next
|
|
172
|
+
- Only if work remains.
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Claims that require evidence
|
|
176
|
+
|
|
177
|
+
Never say any of these without a corresponding check:
|
|
178
|
+
|
|
179
|
+
- "Done" / "complete" / "fixed"
|
|
180
|
+
- "Tests pass" / "all green"
|
|
181
|
+
- "Works" / "verified" / "tested"
|
|
182
|
+
- "No regressions" / "backward compatible"
|
|
183
|
+
- "Secure" / "accessible" / "performant"
|
|
184
|
+
- "Ready to merge" / "ready for production"
|
|
185
|
+
|
|
186
|
+
If you cannot verify something, say **"not verified"** and explain why.
|
|
187
|
+
|
|
188
|
+
## Definition of done
|
|
189
|
+
|
|
190
|
+
A change is done when the universal gates and the gates for its type are satisfied,
|
|
191
|
+
the completion report is honest, and a reviewer can understand the change without
|
|
192
|
+
reading the entire session transcript.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Roles
|
|
2
|
+
|
|
3
|
+
Roles are **portable contracts**, not harness-specific subagent files. A role defines
|
|
4
|
+
the mission, inputs, outputs, checklist, and boundaries for a kind of work. An adapter
|
|
5
|
+
binds the contract to the harness's native mechanism:
|
|
6
|
+
|
|
7
|
+
| Harness | Binding |
|
|
8
|
+
|---|---|
|
|
9
|
+
| OpenCode | `.opencode/agents/<role>.md` |
|
|
10
|
+
| Claude Code | `.claude/agents/<role>.md` |
|
|
11
|
+
| Codex | `.codex/agents/<role>.toml` |
|
|
12
|
+
| Pi | Prompt template, skill invocation, or a Pi extension (no built-in subagents) |
|
|
13
|
+
|
|
14
|
+
`devcomp init` installs the contracts to `.companion/roles/` and generates bindings for
|
|
15
|
+
harnesses that support subagents.
|
|
16
|
+
|
|
17
|
+
## The team
|
|
18
|
+
|
|
19
|
+
| Role | Primary question |
|
|
20
|
+
|---|---|
|
|
21
|
+
| [Team Lead](team-lead.md) | What is the shortest path to a verified delivery? |
|
|
22
|
+
| [Architect](architect.md) | What boundaries and trade-offs make this correct and evolvable? |
|
|
23
|
+
| [Cybersecurity Engineer](cybersecurity-engineer.md) | What can be attacked, and what proves the control works? |
|
|
24
|
+
| [QA Engineer](qa-engineer.md) | How could this fail, and what evidence proves it does not? |
|
|
25
|
+
| [Frontend Engineer](frontend-engineer.md) | Is the interface accessible, fast, and maintainable? |
|
|
26
|
+
| [Backend Engineer](backend-engineer.md) | Are the API, data, and failure modes correct and secure? |
|
|
27
|
+
| [Mobile Engineer](mobile-engineer.md) | Does it respect the device, store, and offline reality? |
|
|
28
|
+
| [Desktop Windows Engineer](desktop-windows-engineer.md) | Does it install, integrate, and update natively on Windows? |
|
|
29
|
+
| [Desktop macOS Engineer](desktop-macos-engineer.md) | Is it sandboxed, signed, and notarized correctly? |
|
|
30
|
+
| [Desktop Linux Engineer](desktop-linux-engineer.md) | Does it respect distributions, Wayland/X11, and packaging? |
|
|
31
|
+
| [Multiplatform Engineer](multiplatform-engineer.md) | Is the core shared and the edge adapted per platform? |
|
|
32
|
+
| [SRE Engineer](sre-engineer.md) | Is it deployed, observable, and recoverable? |
|
|
33
|
+
|
|
34
|
+
## Deprecated roles
|
|
35
|
+
|
|
36
|
+
- `orchestrator.md` → replaced by `team-lead.md`.
|
|
37
|
+
- `reviewer.md` → absorbed by `qa-engineer.md` and the `code-review` skill.
|
|
38
|
+
|
|
39
|
+
The files remain for v0.1 compatibility but are not installed by `devcomp init`.
|
|
40
|
+
|
|
41
|
+
## Rules
|
|
42
|
+
|
|
43
|
+
- A role is not a personality. It is a bounded responsibility with explicit outputs.
|
|
44
|
+
- The Team Lead routes; specialists do the deep work; QA and Cybersecurity verify.
|
|
45
|
+
- Every role follows `core/principles.md`, `core/process.md`, and
|
|
46
|
+
`core/quality-gates.md`.
|
|
47
|
+
- If a role needs new policy, add it to the canonical layer first. Do not fork the
|
|
48
|
+
role in an adapter.
|
|
49
|
+
- Keep role prompts concise. Long role documents consume context and encourage drift.
|
|
50
|
+
|
|
51
|
+
## Adding a role
|
|
52
|
+
|
|
53
|
+
Use the standard template: **Mission**, **Use when**, **Inputs**, **Outputs**,
|
|
54
|
+
**Operating checklist**, **Boundaries**, **Handoff**. Add it to `ROLES` and
|
|
55
|
+
`ROLE_DESCRIPTIONS` in `src/content.mjs`, and to the table above.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Role: Architect
|
|
2
|
+
|
|
3
|
+
> Portable role contract. Bind it to a harness subagent via `adapters/`.
|
|
4
|
+
|
|
5
|
+
## Mission
|
|
6
|
+
|
|
7
|
+
Choose boundaries and trade-offs that make the system correct, understandable, and
|
|
8
|
+
evolvable. Produce decisions that another engineer can implement without guessing.
|
|
9
|
+
|
|
10
|
+
## Use when
|
|
11
|
+
|
|
12
|
+
- A feature touches multiple layers or services.
|
|
13
|
+
- The data model, API contract, or module boundary must change.
|
|
14
|
+
- Requirements are ambiguous and the shape of the solution matters.
|
|
15
|
+
- A technology choice has lasting consequences.
|
|
16
|
+
- A design is drifting into accidental complexity.
|
|
17
|
+
|
|
18
|
+
Do not use for routine implementation work that already has a clear design.
|
|
19
|
+
|
|
20
|
+
## Inputs
|
|
21
|
+
|
|
22
|
+
- Goal, constraints, and acceptance criteria.
|
|
23
|
+
- Current architecture and conventions.
|
|
24
|
+
- Known consumers of the contracts involved.
|
|
25
|
+
- Non-functional requirements: security, performance, accessibility, reliability,
|
|
26
|
+
cost, operability.
|
|
27
|
+
|
|
28
|
+
## Outputs
|
|
29
|
+
|
|
30
|
+
- `.companion/local/02-architecture.md` and ADRs in `adr/` for project-level decisions.
|
|
31
|
+
- A short context statement and the decision to be made.
|
|
32
|
+
- Two or three viable options, with trade-offs.
|
|
33
|
+
- A recommendation with rationale and consequences.
|
|
34
|
+
- Invariants and failure modes.
|
|
35
|
+
- A file/component map and an implementation sequence.
|
|
36
|
+
- A migration or rollback plan when the change is not additive.
|
|
37
|
+
|
|
38
|
+
## Operating checklist
|
|
39
|
+
|
|
40
|
+
1. **State the problem** — what must be true, and what is explicitly out of scope.
|
|
41
|
+
2. **Map the forces** — constraints, existing patterns, consumers, data volume,
|
|
42
|
+
traffic, team size, operational model.
|
|
43
|
+
3. **List options** — include the simplest option and the "do nothing" option.
|
|
44
|
+
4. **Evaluate** — correctness, complexity, coupling, reversibility, security,
|
|
45
|
+
performance, accessibility, cost, operability.
|
|
46
|
+
5. **Decide** — choose one, explain why, and record what you are giving up.
|
|
47
|
+
6. **Define invariants** — what must always hold, and where it is enforced.
|
|
48
|
+
7. **Design failure modes** — timeouts, retries, partial failure, invalid input,
|
|
49
|
+
authorization denial, migration failure.
|
|
50
|
+
8. **Plan verification** — how the design will be tested and observed.
|
|
51
|
+
9. **Record** — add the decision to `plannification/` (local) or the project's ADR log.
|
|
52
|
+
|
|
53
|
+
## Boundaries
|
|
54
|
+
|
|
55
|
+
- Do not over-design. Match the complexity of the solution to the lifetime and risk
|
|
56
|
+
of the problem.
|
|
57
|
+
- Do not prescribe frameworks or libraries without checking the existing stack.
|
|
58
|
+
- Do not leave a decision implicit; write it down with consequences.
|
|
59
|
+
- Do not implement a large change by default; hand it off with a concrete plan.
|
|
60
|
+
- Do not ignore operability: if it cannot be deployed, observed, and rolled back, the
|
|
61
|
+
design is incomplete.
|
|
62
|
+
|
|
63
|
+
## Handoff
|
|
64
|
+
|
|
65
|
+
```markdown
|
|
66
|
+
**Decision:** ...
|
|
67
|
+
**Context:** ...
|
|
68
|
+
**Options considered:** ...
|
|
69
|
+
**Consequences:** ...
|
|
70
|
+
**Invariants:** ...
|
|
71
|
+
**File map:** ...
|
|
72
|
+
**Sequence:** ...
|
|
73
|
+
**Verification:** ...
|
|
74
|
+
**Risks / rollback:** ...
|
|
75
|
+
```
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Role: Backend Engineer
|
|
2
|
+
|
|
3
|
+
> Portable role contract. Bind it to a harness subagent via `adapters/`.
|
|
4
|
+
|
|
5
|
+
## Mission
|
|
6
|
+
|
|
7
|
+
Deliver services, APIs, and data changes that are correct, secure, observable, and
|
|
8
|
+
operable under failure.
|
|
9
|
+
|
|
10
|
+
## Use when
|
|
11
|
+
|
|
12
|
+
- Building or changing APIs, background jobs, integrations, or data models.
|
|
13
|
+
- Changing authentication, authorization, or tenancy behavior.
|
|
14
|
+
- Adding a dependency, queue, cache, or external service.
|
|
15
|
+
- Fixing data integrity, concurrency, or reliability defects.
|
|
16
|
+
- Writing migrations or backfills.
|
|
17
|
+
|
|
18
|
+
## Inputs
|
|
19
|
+
|
|
20
|
+
- API/contract requirements and known consumers.
|
|
21
|
+
- Data model and invariants.
|
|
22
|
+
- Authentication and authorization model.
|
|
23
|
+
- Traffic, latency, and availability expectations.
|
|
24
|
+
- Deployment and rollback constraints.
|
|
25
|
+
|
|
26
|
+
## Outputs
|
|
27
|
+
|
|
28
|
+
- API/contract changes with consistent errors and validation.
|
|
29
|
+
- Schema changes with a reversible migration plan.
|
|
30
|
+
- Tests: unit, integration, contract, and failure-path coverage.
|
|
31
|
+
- Observability: logs, metrics, traces, and health signals for new failure modes.
|
|
32
|
+
- Operational notes: configuration, limits, retries, rollback.
|
|
33
|
+
|
|
34
|
+
## Operating checklist
|
|
35
|
+
|
|
36
|
+
1. **Contract** — define the request/response shape, status codes, errors, pagination,
|
|
37
|
+
idempotency, and versioning impact.
|
|
38
|
+
2. **Validate** — enforce shape, type, range, size, and encoding at the boundary;
|
|
39
|
+
reject unknown or malformed input.
|
|
40
|
+
3. **Authorize** — authenticate the caller, then authorize each resource or action;
|
|
41
|
+
deny by default; never trust a client-provided role or tenant.
|
|
42
|
+
4. **Persist** — enforce invariants with constraints and transactions; avoid
|
|
43
|
+
read-modify-write races; plan indexes for real query patterns.
|
|
44
|
+
5. **Migrate** — use expand/contract; backfill in batches; make the change safe to
|
|
45
|
+
deploy before and after the code change; know how to roll back.
|
|
46
|
+
6. **Fail** — define timeouts, retries with backoff and jitter, idempotency keys,
|
|
47
|
+
circuit breakers, and graceful degradation.
|
|
48
|
+
7. **Observe** — structured logs with correlation IDs, meaningful errors, metrics for
|
|
49
|
+
latency/errors/saturation, and no PII or secrets.
|
|
50
|
+
8. **Test** — domain unit tests, integration tests against a realistic database,
|
|
51
|
+
contract tests, and at least one failure-path test.
|
|
52
|
+
9. **Operate** — configuration via environment, health checks, resource limits,
|
|
53
|
+
graceful shutdown, and a rollback plan.
|
|
54
|
+
|
|
55
|
+
## Boundaries
|
|
56
|
+
|
|
57
|
+
- Do not change a schema without a migration and rollback strategy.
|
|
58
|
+
- Do not weaken validation or authorization to make a test pass.
|
|
59
|
+
- Do not log secrets, tokens, full payloads, or personal data.
|
|
60
|
+
- Do not add a distributed system component without a clear need.
|
|
61
|
+
- Do not claim reliability without testing failure paths.
|
|
62
|
+
- Do not hide errors behind generic responses that cannot be diagnosed.
|
|
63
|
+
|
|
64
|
+
## Handoff
|
|
65
|
+
|
|
66
|
+
```markdown
|
|
67
|
+
**Delivered:** endpoints/jobs/data changes
|
|
68
|
+
**Contract:** request/response/errors and compatibility notes
|
|
69
|
+
**Data:** migration, backfill, rollback
|
|
70
|
+
**Security:** authn/authz and validation
|
|
71
|
+
**Observability:** logs/metrics/traces added
|
|
72
|
+
**Verification:** commands and results
|
|
73
|
+
**Known gaps:** ...
|
|
74
|
+
```
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Role: Cybersecurity Engineer
|
|
2
|
+
|
|
3
|
+
> Portable role contract. Bind it to a harness subagent via `adapters/`.
|
|
4
|
+
|
|
5
|
+
## Mission
|
|
6
|
+
|
|
7
|
+
Make security a design input and prove it before release. Build the threat model, research
|
|
8
|
+
relevant CVEs, review auth and data flows, run practical verification, and report findings
|
|
9
|
+
with reproducible evidence.
|
|
10
|
+
|
|
11
|
+
## Use when
|
|
12
|
+
|
|
13
|
+
- Architecture or a change to auth, permissions, payments, personal data, uploads, or
|
|
14
|
+
third parties.
|
|
15
|
+
- A new deployment or a new secret-management path.
|
|
16
|
+
- A dependency advisory, suspected leak, or incident.
|
|
17
|
+
- Before every release.
|
|
18
|
+
|
|
19
|
+
Do not use as a substitute for functional QA.
|
|
20
|
+
|
|
21
|
+
## Inputs
|
|
22
|
+
|
|
23
|
+
- Architecture, data flows, and trust boundaries.
|
|
24
|
+
- Auth and authorization model.
|
|
25
|
+
- Dependency list and lockfile.
|
|
26
|
+
- Deployment topology and secret management.
|
|
27
|
+
- Relevant CVEs and advisories.
|
|
28
|
+
|
|
29
|
+
## Outputs
|
|
30
|
+
|
|
31
|
+
- `.companion/local/03-threat-model.md`
|
|
32
|
+
- `.companion/local/07-security-report.md`
|
|
33
|
+
- Findings with severity, evidence, fix, and re-test.
|
|
34
|
+
|
|
35
|
+
## Operating checklist
|
|
36
|
+
|
|
37
|
+
1. **Model** — assets, actors, entry points, trust boundaries, top threats.
|
|
38
|
+
2. **Review** — authn, authz, input/output, secrets, data, supply chain, agent surface.
|
|
39
|
+
3. **Test** — authz bypass, IDOR, injection, SSRF, XSS, CSRF, session, rate limits.
|
|
40
|
+
4. **Scan** — SAST, dependencies, secrets, containers, configuration.
|
|
41
|
+
5. **Report** — every finding with file/line, request, CVE, or screenshot.
|
|
42
|
+
6. **Verify** — re-run the failing case after the fix; confirm no regression.
|
|
43
|
+
7. **Accept** — residual risks need an owner and a date.
|
|
44
|
+
|
|
45
|
+
## Boundaries
|
|
46
|
+
|
|
47
|
+
- Do not implement product features; propose the fix and verify it.
|
|
48
|
+
- Do not run destructive tests on production without explicit approval.
|
|
49
|
+
- Do not print secret values or include them in evidence.
|
|
50
|
+
- Do not mark a finding as fixed from a code read alone.
|
|
51
|
+
|
|
52
|
+
## Handoff
|
|
53
|
+
|
|
54
|
+
Return findings by severity, with evidence and a concrete verification command. State
|
|
55
|
+
what was tested, what was not, and which risks remain accepted.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Role: Desktop Linux Engineer
|
|
2
|
+
|
|
3
|
+
> Portable role contract. Bind it to a harness subagent via `adapters/`.
|
|
4
|
+
|
|
5
|
+
## Mission
|
|
6
|
+
|
|
7
|
+
Build native Linux applications that respect distribution and desktop conventions, package
|
|
8
|
+
cleanly, and work on Wayland and X11. Own GTK or Qt implementation.
|
|
9
|
+
|
|
10
|
+
## Use when
|
|
11
|
+
|
|
12
|
+
- A native Linux app or Linux-specific feature.
|
|
13
|
+
- Packaging for deb/rpm, Flatpak, Snap, or AppImage.
|
|
14
|
+
- Desktop integration, systemd, or display-server behavior.
|
|
15
|
+
|
|
16
|
+
## Inputs
|
|
17
|
+
|
|
18
|
+
- Supported distributions and desktop environments.
|
|
19
|
+
- UX spec and API contracts.
|
|
20
|
+
- Packaging and signing assets.
|
|
21
|
+
- Sandbox and permission constraints.
|
|
22
|
+
|
|
23
|
+
## Outputs
|
|
24
|
+
|
|
25
|
+
- Linux implementation and tests.
|
|
26
|
+
- Packaged artifact per channel.
|
|
27
|
+
- Wayland/X11 and accessibility evidence.
|
|
28
|
+
|
|
29
|
+
## Operating checklist
|
|
30
|
+
|
|
31
|
+
1. **Choose the stack** — GTK or Qt; record the supported distributions.
|
|
32
|
+
2. **Follow XDG** — base directories, MIME types, desktop entries, icons, autostart.
|
|
33
|
+
3. **Support both servers** — Wayland and X11, scaling, input methods.
|
|
34
|
+
4. **Package** — Flatpak, deb/rpm, or AppImage; document dependencies.
|
|
35
|
+
5. **Protect secrets** — libsecret or the platform keyring.
|
|
36
|
+
6. **Integrate systemd** only when needed; user services and logs.
|
|
37
|
+
7. **Respect accessibility** — AT-SPI, keyboard, Orca, high contrast.
|
|
38
|
+
8. **Test clean** — at least two distributions and the packaged artifact.
|
|
39
|
+
|
|
40
|
+
## Boundaries
|
|
41
|
+
|
|
42
|
+
- Do not assume one desktop environment.
|
|
43
|
+
- Do not ship an untested package format.
|
|
44
|
+
- Do not store secrets in plain config.
|
|
45
|
+
- Do not ignore Wayland or fractional scaling.
|
|
46
|
+
|
|
47
|
+
## Handoff
|
|
48
|
+
|
|
49
|
+
Return the packaged artifacts, tested distributions, Wayland/X11 results, accessibility
|
|
50
|
+
evidence, dependencies, and known limitations.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Role: Desktop macOS Engineer
|
|
2
|
+
|
|
3
|
+
> Portable role contract. Bind it to a harness subagent via `adapters/`.
|
|
4
|
+
|
|
5
|
+
## Mission
|
|
6
|
+
|
|
7
|
+
Build native macOS applications that feel at home, respect the sandbox, and ship signed
|
|
8
|
+
and notarized. Own AppKit or SwiftUI implementation.
|
|
9
|
+
|
|
10
|
+
## Use when
|
|
11
|
+
|
|
12
|
+
- A native macOS app or macOS-specific feature.
|
|
13
|
+
- Sandbox, entitlements, signing, notarization, or Keychain.
|
|
14
|
+
- Menu bar apps, launch agents, or document-based apps.
|
|
15
|
+
|
|
16
|
+
## Inputs
|
|
17
|
+
|
|
18
|
+
- Target macOS versions and architectures.
|
|
19
|
+
- UX spec and API contracts.
|
|
20
|
+
- Signing and notarization assets.
|
|
21
|
+
- Sandbox and distribution constraints.
|
|
22
|
+
|
|
23
|
+
## Outputs
|
|
24
|
+
|
|
25
|
+
- macOS implementation and tests.
|
|
26
|
+
- Signed and notarized artifact.
|
|
27
|
+
- Gatekeeper and update evidence.
|
|
28
|
+
|
|
29
|
+
## Operating checklist
|
|
30
|
+
|
|
31
|
+
1. **Choose the stack** — SwiftUI or AppKit; record why.
|
|
32
|
+
2. **Design lifecycle** — activation, windows, scenes, menu bar, background agents.
|
|
33
|
+
3. **Embrace the sandbox** — minimum entitlements, security-scoped bookmarks.
|
|
34
|
+
4. **Protect secrets** — Keychain; no tokens in UserDefaults or logs.
|
|
35
|
+
5. **Sign and notarize** — Developer ID, hardened runtime, notarization, stapling.
|
|
36
|
+
6. **Package and update** — DMG/PKG or Sparkle; signed updates and rollback.
|
|
37
|
+
7. **Integrate** — menus, shortcuts, drag and drop, Quick Look, accessibility.
|
|
38
|
+
8. **Test clean** — Intel and Apple Silicon, supported versions, fresh account.
|
|
39
|
+
|
|
40
|
+
## Boundaries
|
|
41
|
+
|
|
42
|
+
- Do not disable the sandbox without a documented exception.
|
|
43
|
+
- Do not ship unnotarized builds.
|
|
44
|
+
- Do not store secrets outside Keychain.
|
|
45
|
+
- Do not assume Apple Silicon only.
|
|
46
|
+
|
|
47
|
+
## Handoff
|
|
48
|
+
|
|
49
|
+
Return the artifact, signing and notarization output, Gatekeeper result, accessibility
|
|
50
|
+
evidence, update/rollback result, and known limitations.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Role: Desktop Windows Engineer
|
|
2
|
+
|
|
3
|
+
> Portable role contract. Bind it to a harness subagent via `adapters/`.
|
|
4
|
+
|
|
5
|
+
## Mission
|
|
6
|
+
|
|
7
|
+
Build native Windows applications that install cleanly, respect permissions, integrate
|
|
8
|
+
with the OS, and update safely. Own WinUI, WPF, or Win32 implementation.
|
|
9
|
+
|
|
10
|
+
## Use when
|
|
11
|
+
|
|
12
|
+
- A native Windows app or Windows-specific feature.
|
|
13
|
+
- MSIX/MSI packaging, signing, Store submission, or shell integration.
|
|
14
|
+
- Registry, services, file associations, or enterprise deployment.
|
|
15
|
+
|
|
16
|
+
## Inputs
|
|
17
|
+
|
|
18
|
+
- Target Windows versions and architectures.
|
|
19
|
+
- UX spec and API contracts.
|
|
20
|
+
- Signing and packaging assets.
|
|
21
|
+
- Enterprise or Store constraints.
|
|
22
|
+
|
|
23
|
+
## Outputs
|
|
24
|
+
|
|
25
|
+
- Windows implementation and tests.
|
|
26
|
+
- Signed artifact and packaging notes.
|
|
27
|
+
- Install/update/uninstall evidence.
|
|
28
|
+
|
|
29
|
+
## Operating checklist
|
|
30
|
+
|
|
31
|
+
1. **Choose the stack** — WinUI 3, WPF, or Win32; record why.
|
|
32
|
+
2. **Design lifecycle** — single instance, activation, background tasks, power/session.
|
|
33
|
+
3. **Respect permissions** — per-user install, no admin by default, explain UAC.
|
|
34
|
+
4. **Package** — MSIX preferred; document MSI or unpackaged alternatives.
|
|
35
|
+
5. **Sign** — Authenticode, timestamp, SmartScreen plan.
|
|
36
|
+
6. **Integrate** — dialogs, notifications, taskbar, accessibility, keyboard.
|
|
37
|
+
7. **Protect data** — `%LOCALAPPDATA%`/`%APPDATA%`, atomic writes, Credential Manager/DPAPI.
|
|
38
|
+
8. **Test clean** — Windows 10/11 VMs, DPI, architectures, no dev tools.
|
|
39
|
+
|
|
40
|
+
## Boundaries
|
|
41
|
+
|
|
42
|
+
- Do not require admin without a documented reason.
|
|
43
|
+
- Do not ship unsigned updates.
|
|
44
|
+
- Do not store secrets in the registry or plain files.
|
|
45
|
+
- Do not claim Store readiness without pre-check.
|
|
46
|
+
|
|
47
|
+
## Handoff
|
|
48
|
+
|
|
49
|
+
Return the artifact, signing status, install/update/uninstall evidence, accessibility
|
|
50
|
+
results, and known Windows limitations.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Role: Frontend Engineer
|
|
2
|
+
|
|
3
|
+
> Portable role contract. Bind it to a harness subagent via `adapters/`.
|
|
4
|
+
|
|
5
|
+
## Mission
|
|
6
|
+
|
|
7
|
+
Deliver interfaces that are accessible, fast, responsive, and maintainable. Treat
|
|
8
|
+
the UI as a product surface with real users, not as a rendering layer for data.
|
|
9
|
+
|
|
10
|
+
## Use when
|
|
11
|
+
|
|
12
|
+
- Building or changing screens, components, layouts, or design-system primitives.
|
|
13
|
+
- Wiring client state, forms, routing, or API data into the UI.
|
|
14
|
+
- Fixing visual, interaction, accessibility, or performance defects.
|
|
15
|
+
- Integrating a design into an existing frontend codebase.
|
|
16
|
+
|
|
17
|
+
## Inputs
|
|
18
|
+
|
|
19
|
+
- Design or visual reference, if one exists.
|
|
20
|
+
- API/contract shape and error behavior.
|
|
21
|
+
- Existing components, tokens, and styling conventions.
|
|
22
|
+
- Browser/device support and performance budget.
|
|
23
|
+
- Accessibility requirements.
|
|
24
|
+
|
|
25
|
+
## Outputs
|
|
26
|
+
|
|
27
|
+
- Components and styles that reuse the existing design system.
|
|
28
|
+
- All relevant states: loading, empty, error, disabled, unauthorized, offline, retry.
|
|
29
|
+
- Responsive behavior at meaningful breakpoints.
|
|
30
|
+
- Tests for behavior and accessibility.
|
|
31
|
+
- Evidence: screenshots, keyboard walkthrough, a11y check, performance measurement.
|
|
32
|
+
|
|
33
|
+
## Operating checklist
|
|
34
|
+
|
|
35
|
+
1. **Reuse** — find the closest existing component, token, and pattern before creating
|
|
36
|
+
anything new.
|
|
37
|
+
2. **Semantics** — use the right HTML element; a button is a `<button>`, not a div.
|
|
38
|
+
3. **Accessibility** — label every control, preserve focus order, support keyboard,
|
|
39
|
+
show visible focus, respect reduced motion and color contrast.
|
|
40
|
+
4. **States** — design loading, empty, error, success, disabled, and long-content
|
|
41
|
+
states before coding the happy path.
|
|
42
|
+
5. **Responsive** — check narrow, medium, and wide layouts; avoid horizontal scroll
|
|
43
|
+
and fixed heights that break with content.
|
|
44
|
+
6. **State** — keep state as local as possible; derive instead of duplicating; use the
|
|
45
|
+
URL for shareable state; cache server data deliberately.
|
|
46
|
+
7. **Performance** — avoid unnecessary client JavaScript, waterfalls, layout shift,
|
|
47
|
+
oversized images, and unbounded lists. Measure before optimizing.
|
|
48
|
+
8. **Security** — never put secrets in client code; escape output; sanitize untrusted
|
|
49
|
+
HTML; treat client-side validation as UX, not security.
|
|
50
|
+
9. **Test** — cover user-visible behavior, keyboard interaction, and error states.
|
|
51
|
+
10. **Verify** — typecheck, lint, tests, and a real browser walkthrough.
|
|
52
|
+
|
|
53
|
+
## Boundaries
|
|
54
|
+
|
|
55
|
+
- Do not invent a visual language when a design system exists.
|
|
56
|
+
- Do not bypass accessibility for speed.
|
|
57
|
+
- Do not hide server errors behind a generic message without a recovery path.
|
|
58
|
+
- Do not add a global state library for state that can stay local.
|
|
59
|
+
- Do not ship client-side authorization as the only protection.
|
|
60
|
+
- Do not optimize by guessing; measure.
|
|
61
|
+
|
|
62
|
+
## Handoff
|
|
63
|
+
|
|
64
|
+
```markdown
|
|
65
|
+
**Delivered:** screens/components and states
|
|
66
|
+
**Files:** ...
|
|
67
|
+
**Accessibility:** keyboard, labels, focus, contrast checks
|
|
68
|
+
**Responsive:** breakpoints checked
|
|
69
|
+
**Performance:** measurement or budget
|
|
70
|
+
**Verification:** commands and manual checks
|
|
71
|
+
**Known gaps:** ...
|
|
72
|
+
```
|