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.
Files changed (82) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +229 -2
  3. package/RELEASE.md +107 -0
  4. package/adapters/README.md +113 -0
  5. package/adapters/claude-code/README.md +81 -0
  6. package/adapters/claude-code/adapter.json +10 -0
  7. package/adapters/cline/adapter.json +9 -0
  8. package/adapters/codex/README.md +80 -0
  9. package/adapters/codex/adapter.json +9 -0
  10. package/adapters/copilot-cli/adapter.json +9 -0
  11. package/adapters/cursor/adapter.json +9 -0
  12. package/adapters/gemini-cli/adapter.json +9 -0
  13. package/adapters/generic/adapter.json +9 -0
  14. package/adapters/opencode/README.md +89 -0
  15. package/adapters/opencode/adapter.json +9 -0
  16. package/adapters/pi/README.md +83 -0
  17. package/adapters/pi/adapter.json +9 -0
  18. package/adapters/windsurf/adapter.json +9 -0
  19. package/bin/devcomp.mjs +8 -0
  20. package/core/guidelines/backend.md +103 -0
  21. package/core/guidelines/collaboration.md +78 -0
  22. package/core/guidelines/frontend.md +106 -0
  23. package/core/guidelines/security.md +90 -0
  24. package/core/guidelines/testing.md +90 -0
  25. package/core/principles.md +208 -0
  26. package/core/process.md +224 -0
  27. package/core/quality-gates.md +192 -0
  28. package/core/roles/README.md +55 -0
  29. package/core/roles/architect.md +75 -0
  30. package/core/roles/backend-engineer.md +74 -0
  31. package/core/roles/cybersecurity-engineer.md +55 -0
  32. package/core/roles/desktop-linux-engineer.md +50 -0
  33. package/core/roles/desktop-macos-engineer.md +50 -0
  34. package/core/roles/desktop-windows-engineer.md +50 -0
  35. package/core/roles/frontend-engineer.md +72 -0
  36. package/core/roles/mobile-engineer.md +50 -0
  37. package/core/roles/multiplatform-engineer.md +49 -0
  38. package/core/roles/orchestrator.md +69 -0
  39. package/core/roles/qa-engineer.md +69 -0
  40. package/core/roles/reviewer.md +77 -0
  41. package/core/roles/sre-engineer.md +51 -0
  42. package/core/roles/team-lead.md +67 -0
  43. package/core/workflow.md +169 -0
  44. package/package.json +53 -4
  45. package/skills/architecture-design/SKILL.md +116 -0
  46. package/skills/backend-development/SKILL.md +127 -0
  47. package/skills/code-review/SKILL.md +144 -0
  48. package/skills/delivery-orchestration/SKILL.md +119 -0
  49. package/skills/deployment-sre/SKILL.md +111 -0
  50. package/skills/desktop-development/SKILL.md +51 -0
  51. package/skills/development-workflow/SKILL.md +158 -0
  52. package/skills/frontend-development/SKILL.md +136 -0
  53. package/skills/linux-development/SKILL.md +44 -0
  54. package/skills/macos-development/SKILL.md +45 -0
  55. package/skills/mobile-development/SKILL.md +60 -0
  56. package/skills/multiplatform-development/SKILL.md +45 -0
  57. package/skills/project-discovery/SKILL.md +122 -0
  58. package/skills/security-review/SKILL.md +109 -0
  59. package/skills/test-strategy/SKILL.md +109 -0
  60. package/skills/ux-design/SKILL.md +108 -0
  61. package/skills/windows-development/SKILL.md +45 -0
  62. package/src/args.mjs +42 -0
  63. package/src/cli.mjs +449 -0
  64. package/src/content.mjs +72 -0
  65. package/src/detect.mjs +119 -0
  66. package/src/install.mjs +186 -0
  67. package/src/prompt.mjs +35 -0
  68. package/src/rules.mjs +83 -0
  69. package/src/scaffold.mjs +433 -0
  70. package/templates/artifacts/01-operational-brief.md +37 -0
  71. package/templates/artifacts/02-architecture.md +33 -0
  72. package/templates/artifacts/03-threat-model.md +29 -0
  73. package/templates/artifacts/04-test-plan.md +35 -0
  74. package/templates/artifacts/05-ux-spec.md +31 -0
  75. package/templates/artifacts/06-delivery-plan.md +29 -0
  76. package/templates/artifacts/07-security-report.md +25 -0
  77. package/templates/artifacts/08-qa-report.md +32 -0
  78. package/templates/artifacts/09-runbook.md +43 -0
  79. package/templates/artifacts/10-closure.md +25 -0
  80. package/templates/artifacts/README.md +17 -0
  81. package/templates/rules/AGENTS.block.md +36 -0
  82. 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.