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,158 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: development-workflow
|
|
3
|
+
description: Run a disciplined end-to-end workflow for features, bug fixes, refactors, and other code changes. Use when starting non-trivial implementation work, when a task spans multiple files or layers, when the user asks for a plan, or before claiming a change is complete.
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: "0.1.0"
|
|
7
|
+
author: development-companion
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Development Workflow
|
|
11
|
+
|
|
12
|
+
Use this skill to move from a request to a verified change without skipping
|
|
13
|
+
understanding, planning, or evidence.
|
|
14
|
+
|
|
15
|
+
## When to use
|
|
16
|
+
|
|
17
|
+
- A feature or bug fix touches more than one file or layer.
|
|
18
|
+
- The requirements are ambiguous or the change is risky.
|
|
19
|
+
- The user asks for a plan, an implementation, or a review.
|
|
20
|
+
- You are about to say "done" and need a completion checklist.
|
|
21
|
+
- A task has grown beyond its original scope.
|
|
22
|
+
|
|
23
|
+
For a typo or a one-line docs fix, use a short version: recon, change, check, report.
|
|
24
|
+
|
|
25
|
+
## Inputs
|
|
26
|
+
|
|
27
|
+
- The user's request and constraints.
|
|
28
|
+
- The repository, its conventions, and the relevant tests.
|
|
29
|
+
- Any design, issue, or acceptance criteria available.
|
|
30
|
+
- The project's rules file (`AGENTS.md`, `CLAUDE.md`, or equivalent).
|
|
31
|
+
|
|
32
|
+
## Workflow
|
|
33
|
+
|
|
34
|
+
### 1. Classify
|
|
35
|
+
|
|
36
|
+
Identify the task type: bug fix, feature, refactor, docs, ops/config, or spike.
|
|
37
|
+
Choose the minimum rigor it needs. If it mixes types, split it.
|
|
38
|
+
|
|
39
|
+
### 2. Recon
|
|
40
|
+
|
|
41
|
+
- Read the closest existing implementation and the tests around it.
|
|
42
|
+
- Trace the entry point and data flow; do not infer from filenames.
|
|
43
|
+
- Find all call sites of contracts you may change.
|
|
44
|
+
- Check local conventions: naming, structure, errors, styling, test style.
|
|
45
|
+
- List the relevant files and the unknowns.
|
|
46
|
+
|
|
47
|
+
**Output:** a short recon summary with file references.
|
|
48
|
+
|
|
49
|
+
### 3. Frame
|
|
50
|
+
|
|
51
|
+
Write a task brief:
|
|
52
|
+
|
|
53
|
+
```markdown
|
|
54
|
+
**Goal**
|
|
55
|
+
What must be true when this is done?
|
|
56
|
+
|
|
57
|
+
**Non-goals**
|
|
58
|
+
What is explicitly out of scope?
|
|
59
|
+
|
|
60
|
+
**Acceptance criteria**
|
|
61
|
+
Observable conditions that prove success.
|
|
62
|
+
|
|
63
|
+
**Constraints**
|
|
64
|
+
Compatibility, platforms, performance, security, dependencies.
|
|
65
|
+
|
|
66
|
+
**Unknowns**
|
|
67
|
+
What must be checked or decided first?
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
If the goal or acceptance criteria are ambiguous, ask before coding.
|
|
71
|
+
|
|
72
|
+
### 4. Plan
|
|
73
|
+
|
|
74
|
+
For non-trivial work, state:
|
|
75
|
+
|
|
76
|
+
1. Approach and why (including alternatives considered).
|
|
77
|
+
2. Files to create/modify/delete.
|
|
78
|
+
3. Contract changes: APIs, schemas, types, events, UI props.
|
|
79
|
+
4. Risks and how you will detect them.
|
|
80
|
+
5. Exact verification commands and manual checks.
|
|
81
|
+
6. Rollback or migration plan when relevant.
|
|
82
|
+
|
|
83
|
+
Keep the plan proportional to the change.
|
|
84
|
+
|
|
85
|
+
### 5. Implement
|
|
86
|
+
|
|
87
|
+
- Follow the plan; revise it if reality contradicts it.
|
|
88
|
+
- Match existing patterns before adding abstractions.
|
|
89
|
+
- Keep the diff scoped; no drive-by refactors.
|
|
90
|
+
- Validate at boundaries, handle errors explicitly, no silent failures.
|
|
91
|
+
- Add or update tests with the behavior.
|
|
92
|
+
- Remove debug code, temp files, and commented-out blocks.
|
|
93
|
+
|
|
94
|
+
**Stop and ask** if requirements conflict, the change affects auth/data/money without
|
|
95
|
+
approval, a public contract has unknown consumers, unrelated tests fail, or you cannot
|
|
96
|
+
verify the result.
|
|
97
|
+
|
|
98
|
+
### 6. Verify
|
|
99
|
+
|
|
100
|
+
Use the strongest evidence available:
|
|
101
|
+
|
|
102
|
+
1. Static checks: typecheck, lint, schema validation.
|
|
103
|
+
2. Unit tests: logic, invariants, edge cases.
|
|
104
|
+
3. Integration tests: real database/API/component boundaries.
|
|
105
|
+
4. End-to-end or manual: the actual user/system flow.
|
|
106
|
+
5. Performance/security checks where relevant.
|
|
107
|
+
|
|
108
|
+
Report what ran, what passed, and what could not run. A skipped check is a known risk.
|
|
109
|
+
|
|
110
|
+
### 7. Review and report
|
|
111
|
+
|
|
112
|
+
Read your own diff as a reviewer. Check for accidental changes, secrets, missing
|
|
113
|
+
states, and stale docs. Then report:
|
|
114
|
+
|
|
115
|
+
```markdown
|
|
116
|
+
## Delivered
|
|
117
|
+
- What changed and why.
|
|
118
|
+
|
|
119
|
+
## Verification
|
|
120
|
+
- Command/check → result.
|
|
121
|
+
- Manual check → observed result.
|
|
122
|
+
|
|
123
|
+
## Risks and not covered
|
|
124
|
+
- Residual risk, skipped checks, follow-ups.
|
|
125
|
+
|
|
126
|
+
## Next
|
|
127
|
+
- Only if work remains.
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Stop conditions
|
|
131
|
+
|
|
132
|
+
Do not continue past these without clarification:
|
|
133
|
+
|
|
134
|
+
- Requirements conflict or acceptance criteria are untestable.
|
|
135
|
+
- Authentication, authorization, payments, personal data, or destructive migrations
|
|
136
|
+
are involved without explicit approval.
|
|
137
|
+
- A public contract must change and consumers are unknown.
|
|
138
|
+
- Tests fail for reasons unrelated to the change.
|
|
139
|
+
- The correct fix requires scope far beyond the request.
|
|
140
|
+
- There is no way to verify the result.
|
|
141
|
+
|
|
142
|
+
## Quality bar
|
|
143
|
+
|
|
144
|
+
- The smallest coherent diff that fully solves the problem.
|
|
145
|
+
- Evidence for every claim of "done", "tested", or "works".
|
|
146
|
+
- Security, accessibility, and performance considered from the start.
|
|
147
|
+
- No secrets, debug output, or unrelated changes.
|
|
148
|
+
- Honest reporting of residual risk.
|
|
149
|
+
|
|
150
|
+
## Anti-patterns
|
|
151
|
+
|
|
152
|
+
- Coding before understanding the flow.
|
|
153
|
+
- A plan that is just a file list with no risks or verification.
|
|
154
|
+
- Mixing refactors with behavior changes.
|
|
155
|
+
- Fixing the symptom and declaring the bug closed.
|
|
156
|
+
- Running tests but not reading the failures.
|
|
157
|
+
- Claiming completion from memory instead of evidence.
|
|
158
|
+
- Expanding scope without telling the user.
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: frontend-development
|
|
3
|
+
description: Build or modify accessible, fast, maintainable user interfaces. Use when working on screens, components, layouts, design-system primitives, client state, forms, routing, or frontend performance and accessibility issues.
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: "0.1.0"
|
|
7
|
+
author: development-companion
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Frontend Development
|
|
11
|
+
|
|
12
|
+
Deliver UI that works for real users: accessible, responsive, fast, and consistent
|
|
13
|
+
with the existing design system.
|
|
14
|
+
|
|
15
|
+
## Before coding
|
|
16
|
+
|
|
17
|
+
1. Find the closest existing screen, component, token, and test. Reuse before creating.
|
|
18
|
+
2. Identify the data contract: loading, success, empty, error, unauthorized, offline.
|
|
19
|
+
3. Check the design system: colors, spacing, typography, radii, motion, breakpoints.
|
|
20
|
+
4. Check the project's conventions: file structure, styling approach, state management,
|
|
21
|
+
data fetching, test utilities.
|
|
22
|
+
5. Confirm browser/device support and any performance budget.
|
|
23
|
+
|
|
24
|
+
## Implementation checklist
|
|
25
|
+
|
|
26
|
+
### Structure
|
|
27
|
+
|
|
28
|
+
- [ ] Organize by feature or route, not by file type.
|
|
29
|
+
- [ ] Keep state as local as possible; derive instead of duplicating.
|
|
30
|
+
- [ ] Put shareable/navigation state in the URL.
|
|
31
|
+
- [ ] Keep side effects at the edges; keep rendering pure.
|
|
32
|
+
- [ ] Avoid components with dozens of boolean props; compose instead.
|
|
33
|
+
|
|
34
|
+
### Semantics and accessibility
|
|
35
|
+
|
|
36
|
+
- [ ] Use the correct HTML element: `<button>`, `<a>`, `<input>`, headings in order.
|
|
37
|
+
- [ ] Every control has an accessible name; placeholders are not labels.
|
|
38
|
+
- [ ] Keyboard: all interactive elements are reachable and operable.
|
|
39
|
+
- [ ] Focus is visible and managed on route/dialog changes.
|
|
40
|
+
- [ ] Errors are associated with their fields and announced.
|
|
41
|
+
- [ ] Images have alt text; decorative images use empty alt.
|
|
42
|
+
- [ ] Color is not the only signal; contrast meets WCAG AA.
|
|
43
|
+
- [ ] `prefers-reduced-motion` is respected.
|
|
44
|
+
- [ ] Icon-only buttons have labels.
|
|
45
|
+
|
|
46
|
+
### States
|
|
47
|
+
|
|
48
|
+
Implement and test:
|
|
49
|
+
|
|
50
|
+
- [ ] Loading (skeleton or progress, not a blank screen).
|
|
51
|
+
- [ ] Empty (clear next action).
|
|
52
|
+
- [ ] Error (specific message, retry path).
|
|
53
|
+
- [ ] Success.
|
|
54
|
+
- [ ] Disabled / read-only.
|
|
55
|
+
- [ ] Unauthorized / forbidden.
|
|
56
|
+
- [ ] Offline / slow network where relevant.
|
|
57
|
+
- [ ] Long content, overflow, and narrow width.
|
|
58
|
+
|
|
59
|
+
### Responsive
|
|
60
|
+
|
|
61
|
+
- [ ] Check narrow, medium, and wide layouts.
|
|
62
|
+
- [ ] No horizontal scroll unless intentional.
|
|
63
|
+
- [ ] Touch targets are large enough.
|
|
64
|
+
- [ ] Fixed heights do not break with content or zoom.
|
|
65
|
+
- [ ] Text remains readable at 200% zoom.
|
|
66
|
+
|
|
67
|
+
### Performance
|
|
68
|
+
|
|
69
|
+
- [ ] Measure before optimizing.
|
|
70
|
+
- [ ] Avoid request waterfalls; fetch independent data in parallel.
|
|
71
|
+
- [ ] Split code by route or heavy interaction.
|
|
72
|
+
- [ ] Reserve space for images/async content to prevent layout shift.
|
|
73
|
+
- [ ] Optimize images: responsive sizes, modern formats, explicit dimensions.
|
|
74
|
+
- [ ] Virtualize or paginate long lists.
|
|
75
|
+
- [ ] Keep third-party scripts out of the critical path.
|
|
76
|
+
- [ ] Respect budgets (e.g. LCP < 2.5 s, INP < 200 ms, CLS < 0.1).
|
|
77
|
+
|
|
78
|
+
### Security
|
|
79
|
+
|
|
80
|
+
- [ ] No secrets, private keys, or privileged tokens in client code.
|
|
81
|
+
- [ ] Untrusted content is escaped; rich HTML is sanitized.
|
|
82
|
+
- [ ] No `dangerouslySetInnerHTML`/`v-html` without a reviewed reason.
|
|
83
|
+
- [ ] Authorization is enforced by the server, not only the UI.
|
|
84
|
+
- [ ] Sensitive data is not put in URLs, logs, or analytics.
|
|
85
|
+
|
|
86
|
+
### Testing
|
|
87
|
+
|
|
88
|
+
- [ ] Tests assert user-visible behavior, not implementation details.
|
|
89
|
+
- [ ] Queries use roles and labels, not brittle CSS selectors.
|
|
90
|
+
- [ ] Keyboard interaction and form errors are covered.
|
|
91
|
+
- [ ] Loading/empty/error states are covered where they matter.
|
|
92
|
+
- [ ] Network boundaries are mocked, not the component's own logic.
|
|
93
|
+
|
|
94
|
+
## Verification
|
|
95
|
+
|
|
96
|
+
Run the project's checks:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
# examples; use the project's actual commands
|
|
100
|
+
<typecheck>
|
|
101
|
+
<lint>
|
|
102
|
+
<test>
|
|
103
|
+
<build>
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Then verify manually in a browser:
|
|
107
|
+
|
|
108
|
+
1. Walk the happy path.
|
|
109
|
+
2. Use keyboard only.
|
|
110
|
+
3. Trigger loading, empty, and error states.
|
|
111
|
+
4. Resize to narrow and wide breakpoints.
|
|
112
|
+
5. Check the console and network panel for errors.
|
|
113
|
+
6. Take a screenshot for UI changes when useful.
|
|
114
|
+
|
|
115
|
+
## Output
|
|
116
|
+
|
|
117
|
+
Report:
|
|
118
|
+
|
|
119
|
+
- Screens/components and states delivered.
|
|
120
|
+
- Files changed.
|
|
121
|
+
- Accessibility checks performed.
|
|
122
|
+
- Responsive breakpoints checked.
|
|
123
|
+
- Performance measurement or budget.
|
|
124
|
+
- Verification commands and results.
|
|
125
|
+
- Known gaps.
|
|
126
|
+
|
|
127
|
+
## Anti-patterns
|
|
128
|
+
|
|
129
|
+
- Divs with click handlers instead of buttons.
|
|
130
|
+
- Placeholder-only labels.
|
|
131
|
+
- Hiding errors behind a generic toast with no recovery.
|
|
132
|
+
- Global state for local UI concerns.
|
|
133
|
+
- Shipping secrets or privileged logic to the client.
|
|
134
|
+
- Optimizing without measuring.
|
|
135
|
+
- Testing CSS classes instead of behavior.
|
|
136
|
+
- Leaving loading/empty/error states for later.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: linux-development
|
|
3
|
+
description: Build native Linux applications with GTK or Qt, including packaging, XDG conventions, Wayland/X11, systemd, and secrets. Use for Linux-specific desktop work.
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: "1.0.0"
|
|
7
|
+
author: development-companion
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Linux Development
|
|
11
|
+
|
|
12
|
+
Linux is a family of distributions, not a single target. Package for the ones you support
|
|
13
|
+
and respect the desktop conventions.
|
|
14
|
+
|
|
15
|
+
## When to use
|
|
16
|
+
|
|
17
|
+
- A native Linux app or Linux-specific feature.
|
|
18
|
+
- Packaging for deb/rpm, Flatpak, Snap, or AppImage.
|
|
19
|
+
- Desktop integration, systemd, or Wayland/X11 behavior.
|
|
20
|
+
|
|
21
|
+
## Procedure
|
|
22
|
+
|
|
23
|
+
1. **Choose the stack.** GTK for GNOME; Qt for KDE/cross-desktop. Record the reason and
|
|
24
|
+
the supported distributions.
|
|
25
|
+
2. **Follow XDG.** Use XDG base directories, MIME types, desktop entries, icons, and
|
|
26
|
+
autostart correctly.
|
|
27
|
+
3. **Support both display servers.** Test Wayland and X11; handle scaling, fractional
|
|
28
|
+
scaling, and input methods.
|
|
29
|
+
4. **Package for the channel.** Flatpak for sandboxed distribution; deb/rpm for distro
|
|
30
|
+
integration; AppImage for portable use. Document dependencies.
|
|
31
|
+
5. **Protect secrets.** Use libsecret or the platform keyring; never plain-text config.
|
|
32
|
+
6. **Integrate with systemd** only when needed; user services, sandboxing, and logs.
|
|
33
|
+
7. **Respect accessibility.** AT-SPI, keyboard navigation, Orca, and high contrast.
|
|
34
|
+
8. **Test on clean distributions.** At least one Debian/Ubuntu and one Fedora/Arch target,
|
|
35
|
+
plus the packaged artifact.
|
|
36
|
+
|
|
37
|
+
## Verification
|
|
38
|
+
|
|
39
|
+
- Install, launch, update, and uninstall tested from the packaged artifact.
|
|
40
|
+
- Wayland and X11 behavior verified.
|
|
41
|
+
- XDG paths and desktop entries correct.
|
|
42
|
+
- No secret in config, logs, or crash reports.
|
|
43
|
+
- Accessibility verified with Orca and keyboard.
|
|
44
|
+
- Dependencies and licenses documented.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: macos-development
|
|
3
|
+
description: Build native macOS applications with AppKit or SwiftUI, including sandboxing, entitlements, signing, notarization, and Keychain. Use for macOS-specific desktop work.
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: "1.0.0"
|
|
7
|
+
author: development-companion
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# macOS Development
|
|
11
|
+
|
|
12
|
+
macOS rewards apps that feel native and punish those that fight the sandbox. Design with
|
|
13
|
+
entitlements and notarization from day one.
|
|
14
|
+
|
|
15
|
+
## When to use
|
|
16
|
+
|
|
17
|
+
- A native macOS app or macOS-specific feature.
|
|
18
|
+
- Sandbox, entitlements, signing, or notarization.
|
|
19
|
+
- Menu bar apps, launch agents, or document-based apps.
|
|
20
|
+
|
|
21
|
+
## Procedure
|
|
22
|
+
|
|
23
|
+
1. **Choose the stack.** SwiftUI for new apps; AppKit for deep control or existing code.
|
|
24
|
+
Record the trade-off.
|
|
25
|
+
2. **Design the lifecycle.** Activation, windows, scenes, menu bar, background agents, and
|
|
26
|
+
state restoration.
|
|
27
|
+
3. **Embrace the sandbox.** Request the minimum entitlements; use security-scoped
|
|
28
|
+
bookmarks for user-selected files; never disable the sandbox casually.
|
|
29
|
+
4. **Protect secrets.** Keychain for tokens; no secrets in UserDefaults or logs.
|
|
30
|
+
5. **Sign and notarize.** Developer ID, hardened runtime, notarization, stapling, and
|
|
31
|
+
Gatekeeper verification.
|
|
32
|
+
6. **Package and update.** DMG/PKG or Sparkle; signed updates and rollback.
|
|
33
|
+
7. **Integrate natively.** Menus, shortcuts, drag and drop, Quick Look, notifications, and
|
|
34
|
+
accessibility (VoiceOver, keyboard, dynamic type).
|
|
35
|
+
8. **Test on clean machines.** Intel and Apple Silicon, supported macOS versions, and a
|
|
36
|
+
fresh user account.
|
|
37
|
+
|
|
38
|
+
## Verification
|
|
39
|
+
|
|
40
|
+
- App launches from a quarantined download and passes Gatekeeper.
|
|
41
|
+
- Sandbox entitlements are minimal and documented.
|
|
42
|
+
- Signing and notarization verified with `codesign`/`spctl`.
|
|
43
|
+
- Keychain used for secrets; no secret in logs.
|
|
44
|
+
- Accessibility and keyboard navigation verified.
|
|
45
|
+
- Update and rollback tested.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mobile-development
|
|
3
|
+
description: Build and verify iOS and Android applications with correct permissions, offline behavior, performance, accessibility, and store release constraints. Use for native or cross-platform mobile work.
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: "1.0.0"
|
|
7
|
+
author: development-companion
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Mobile Development
|
|
11
|
+
|
|
12
|
+
Mobile is a constrained platform: battery, network, permissions, store review, and device
|
|
13
|
+
fragmentation. Design for the constraints, not for the simulator.
|
|
14
|
+
|
|
15
|
+
## When to use
|
|
16
|
+
|
|
17
|
+
- A new mobile app or a new mobile flow.
|
|
18
|
+
- Permissions, push notifications, deep links, offline, or background work.
|
|
19
|
+
- A store submission or a platform upgrade.
|
|
20
|
+
|
|
21
|
+
## Inputs
|
|
22
|
+
|
|
23
|
+
- Target platforms and minimum OS versions.
|
|
24
|
+
- Device and screen matrix.
|
|
25
|
+
- Auth, data, and offline requirements.
|
|
26
|
+
- Store policies and signing assets.
|
|
27
|
+
|
|
28
|
+
## Procedure
|
|
29
|
+
|
|
30
|
+
1. **Choose the approach.** Native (Swift/Kotlin) when platform APIs or performance
|
|
31
|
+
matter; cross-platform (Flutter/React Native/KMP) when shared logic and speed dominate.
|
|
32
|
+
Record the trade-off.
|
|
33
|
+
2. **Design the flow.** Every screen defines loading, empty, error, offline, permission
|
|
34
|
+
denied, and success. Handle interruptions and app restoration.
|
|
35
|
+
3. **Handle permissions.** Ask in context, explain why, and provide a degraded path. Never
|
|
36
|
+
block the app on an optional permission.
|
|
37
|
+
4. **Design offline.** Cache, queue, conflict resolution, retry, and visible sync state.
|
|
38
|
+
Do not pretend the network is reliable.
|
|
39
|
+
5. **Protect data.** Keychain/Keystore for tokens; no secrets in code or logs; certificate
|
|
40
|
+
pinning only with a rotation plan.
|
|
41
|
+
6. **Meet platform quality bars.** Startup time, frame budget, memory, battery, accessibility
|
|
42
|
+
(VoiceOver/TalkBack), dynamic type, dark mode, and reduced motion.
|
|
43
|
+
7. **Prepare release.** Versioning, signing, store metadata, privacy manifest, screenshots,
|
|
44
|
+
staged rollout, and crash monitoring.
|
|
45
|
+
8. **Test on real devices.** Emulators are not evidence for performance, camera, Bluetooth,
|
|
46
|
+
biometrics, or battery.
|
|
47
|
+
|
|
48
|
+
## Verification
|
|
49
|
+
|
|
50
|
+
- Critical flows tested on at least one physical device per platform.
|
|
51
|
+
- Offline and permission-denied paths exercised.
|
|
52
|
+
- Accessibility labels and focus order checked.
|
|
53
|
+
- No token or secret in logs, screenshots, or repository.
|
|
54
|
+
- Store pre-checks pass; rollout and rollback plan documented.
|
|
55
|
+
- Performance measured on a low-end reference device.
|
|
56
|
+
|
|
57
|
+
## Output
|
|
58
|
+
|
|
59
|
+
`.companion/local/evidence/mobile/` with screenshots, device matrix, performance results,
|
|
60
|
+
and release checklist.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: multiplatform-development
|
|
3
|
+
description: Build a shared core with per-platform adapters using Tauri, Flutter, Kotlin Multiplatform, or .NET MAUI. Use when one product must ship on web, mobile, and desktop without duplicating the domain.
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: "1.0.0"
|
|
7
|
+
author: development-companion
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Multiplatform Development
|
|
11
|
+
|
|
12
|
+
Share the domain and contracts; adapt the edges. A multiplatform app that ignores platform
|
|
13
|
+
differences feels wrong everywhere.
|
|
14
|
+
|
|
15
|
+
## When to use
|
|
16
|
+
|
|
17
|
+
- One product across web, mobile, and desktop.
|
|
18
|
+
- Choosing Tauri, Flutter, KMP/Compose, or .NET MAUI.
|
|
19
|
+
- A shared core with platform-specific UI or native modules.
|
|
20
|
+
|
|
21
|
+
## Procedure
|
|
22
|
+
|
|
23
|
+
1. **Define the shared boundary.** Domain, use cases, contracts, validation, and state
|
|
24
|
+
machines are shared. UI, permissions, storage, and OS integration are platform-specific.
|
|
25
|
+
2. **Choose the runtime.** Tauri for web UI + Rust core; Flutter for a unified UI; KMP for
|
|
26
|
+
shared Kotlin logic with native UI; MAUI for .NET teams. Record the trade-off.
|
|
27
|
+
3. **Design platform adapters.** Each platform implements the same ports: storage, auth,
|
|
28
|
+
notifications, files, deep links, and analytics.
|
|
29
|
+
4. **Handle UI differences.** Navigation, back behavior, typography, accessibility, and
|
|
30
|
+
input models differ. Do not ship one UI unchanged to every platform.
|
|
31
|
+
5. **Build a release matrix.** Per-platform signing, packaging, store rules, and update
|
|
32
|
+
channels.
|
|
33
|
+
6. **Test the matrix.** Unit tests on the shared core; integration and visual tests per
|
|
34
|
+
platform; device tests where native APIs are involved.
|
|
35
|
+
7. **Measure size and performance.** Shared runtimes add weight; set budgets for startup,
|
|
36
|
+
memory, and bundle size.
|
|
37
|
+
|
|
38
|
+
## Verification
|
|
39
|
+
|
|
40
|
+
- Shared core has no platform-specific imports.
|
|
41
|
+
- Every port has an adapter per supported platform.
|
|
42
|
+
- UI reviewed on each platform, not only the primary one.
|
|
43
|
+
- Signing and packaging pass per platform.
|
|
44
|
+
- Performance and size within budget on a low-end device.
|
|
45
|
+
- Release matrix documented with owners.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: project-discovery
|
|
3
|
+
description: Run the operational and technical discovery for a new project or a major change. Use when starting a project, adopting an existing repository, or when scope, stack, hosting, integrations, authentication, or success criteria are unclear.
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: "1.0.0"
|
|
7
|
+
author: development-companion
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Project Discovery
|
|
11
|
+
|
|
12
|
+
Discovery is not a formality. It decides whether the rest of the work is solving the
|
|
13
|
+
right problem with the right constraints. Ask before building.
|
|
14
|
+
|
|
15
|
+
## When to use
|
|
16
|
+
|
|
17
|
+
- A new project, product, or MVP.
|
|
18
|
+
- A major feature that changes architecture, data, auth, or deployment.
|
|
19
|
+
- An existing repository with unknown conventions, history, or ownership.
|
|
20
|
+
- The user cannot yet state acceptance criteria in observable terms.
|
|
21
|
+
|
|
22
|
+
For a small change inside a known system, use the short brief in
|
|
23
|
+
`development-workflow` instead.
|
|
24
|
+
|
|
25
|
+
## Inputs
|
|
26
|
+
|
|
27
|
+
- The user's idea, goals, and constraints.
|
|
28
|
+
- Access to existing repositories, designs, tickets, or prototypes.
|
|
29
|
+
- The current repository, if there is one.
|
|
30
|
+
- Any compliance, security, or platform requirements.
|
|
31
|
+
|
|
32
|
+
## Procedure
|
|
33
|
+
|
|
34
|
+
### 1. Operational discovery
|
|
35
|
+
|
|
36
|
+
Ask one topic at a time. Record answers verbatim where they matter.
|
|
37
|
+
|
|
38
|
+
**Problem and users**
|
|
39
|
+
- What problem does this solve, and for whom?
|
|
40
|
+
- What happens today without it?
|
|
41
|
+
- Who are the primary and secondary users?
|
|
42
|
+
|
|
43
|
+
**Outcome**
|
|
44
|
+
- What must be true for this to be a success?
|
|
45
|
+
- Which metrics or observable behaviors prove it?
|
|
46
|
+
- What is explicitly out of scope for the first release?
|
|
47
|
+
|
|
48
|
+
**Reality**
|
|
49
|
+
- Are there existing repositories, prototypes, designs, or documents? Clone or reference
|
|
50
|
+
them; do not rebuild what exists.
|
|
51
|
+
- What is the deadline, team, budget, and maintenance capacity?
|
|
52
|
+
- What legal, privacy, or compliance constraints apply?
|
|
53
|
+
|
|
54
|
+
**Operations**
|
|
55
|
+
- Where will it run: on-prem, VPS, Dokploy, Coolify, cloud?
|
|
56
|
+
- Which third-party services, APIs, MCPs, or on-device capabilities are required?
|
|
57
|
+
- What data is stored, where, and for how long?
|
|
58
|
+
- What authentication is needed: local, OIDC, Firebase, other?
|
|
59
|
+
- Which platforms are targets: web, mobile, desktop, multiplatform, TV, watch?
|
|
60
|
+
|
|
61
|
+
**Delivery conventions**
|
|
62
|
+
- Which branch convention is used: gitflow, GitLab flow, trunk-based, GitHub flow, or
|
|
63
|
+
custom? Detect the current one and ask the user to confirm; never assume.
|
|
64
|
+
- How are releases, hotfixes, and reviews handled?
|
|
65
|
+
- Is there a definition of done beyond "it works"?
|
|
66
|
+
|
|
67
|
+
### 2. Technical discovery
|
|
68
|
+
|
|
69
|
+
Only after the operational picture is clear.
|
|
70
|
+
|
|
71
|
+
- Stack and versions: verify the latest stable release; do not invent version numbers.
|
|
72
|
+
- Repository layout: monorepo or single repo; workspace tool.
|
|
73
|
+
- Architecture: monolith, modular monolith, or microservices; why.
|
|
74
|
+
- Domain complexity: simple layered, hexagonal, or tactical DDD.
|
|
75
|
+
- Data: relational, document, key-value, files, on-device; migrations.
|
|
76
|
+
- Integrations: sync/async, retries, idempotency, rate limits, webhooks.
|
|
77
|
+
- AuthN/AuthZ: sessions, tokens, OIDC, roles, tenancy.
|
|
78
|
+
- Deployment, secrets, observability, backups, rollback.
|
|
79
|
+
- Performance budgets and expected load.
|
|
80
|
+
|
|
81
|
+
### 3. Reconcile and confirm
|
|
82
|
+
|
|
83
|
+
- Summarize the brief in the user's language.
|
|
84
|
+
- List assumptions, unknowns, and decisions that need the user.
|
|
85
|
+
- Do not proceed to architecture while a blocking question is open.
|
|
86
|
+
|
|
87
|
+
## Output
|
|
88
|
+
|
|
89
|
+
Write `.companion/local/01-operational-brief.md` with:
|
|
90
|
+
|
|
91
|
+
```markdown
|
|
92
|
+
# Operational brief
|
|
93
|
+
|
|
94
|
+
## Problem and users
|
|
95
|
+
## Goals and success metrics
|
|
96
|
+
## Scope and non-goals
|
|
97
|
+
## Existing artifacts
|
|
98
|
+
## Constraints
|
|
99
|
+
## Hosting and third parties
|
|
100
|
+
## Data and auth
|
|
101
|
+
## Platforms
|
|
102
|
+
## Branch convention
|
|
103
|
+
## Definition of done
|
|
104
|
+
## Open questions
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Add a short technical addendum if the discovery already covered stack decisions.
|
|
108
|
+
|
|
109
|
+
## Verification
|
|
110
|
+
|
|
111
|
+
- Every section has an answer or an explicit "unknown".
|
|
112
|
+
- The user confirmed the brief.
|
|
113
|
+
- The branch convention is recorded with its source: detected, user, or default.
|
|
114
|
+
- No acceptance criterion is untestable.
|
|
115
|
+
- No secret values were read or printed.
|
|
116
|
+
|
|
117
|
+
## Anti-patterns
|
|
118
|
+
|
|
119
|
+
- Asking twenty questions in one message.
|
|
120
|
+
- Assuming a stack because it is popular.
|
|
121
|
+
- Skipping discovery because "the user already knows".
|
|
122
|
+
- Writing code to "clarify" requirements.
|