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,109 @@
1
+ ---
2
+ name: security-review
3
+ description: Build a threat model and verify security with evidence before release. Use during architecture, before deploying, after adding auth or data flows, or when a vulnerability, CVE, or secret-handling concern appears.
4
+ license: MIT
5
+ metadata:
6
+ version: "1.0.0"
7
+ author: development-companion
8
+ ---
9
+
10
+ # Security Review
11
+
12
+ Security is a design input, not a final checklist. Every finding needs evidence and a
13
+ verification.
14
+
15
+ ## When to use
16
+
17
+ - Architecture phase, before implementation.
18
+ - Any change to auth, permissions, payments, personal data, uploads, or third parties.
19
+ - Before a release or a deployment.
20
+ - A dependency advisory, CVE, or suspected secret leak.
21
+
22
+ Do not use this skill to replace functional QA.
23
+
24
+ ## Inputs
25
+
26
+ - Architecture, data flows, and trust boundaries.
27
+ - Auth and authorization model.
28
+ - Deployment topology and secret management.
29
+ - Dependency list and lockfile.
30
+ - Relevant CVEs and advisories.
31
+
32
+ ## Procedure
33
+
34
+ ### 1. Model the threats
35
+
36
+ - Assets: data, credentials, money, availability, reputation.
37
+ - Actors: anonymous, user, admin, service, insider, attacker.
38
+ - Entry points: HTTP, UI, jobs, webhooks, files, CLI, MCP, third parties.
39
+ - Trust boundaries and data crossings.
40
+ - STRIDE or an equivalent lens; record the top risks.
41
+
42
+ ### 2. Review the design
43
+
44
+ - AuthN: session, token, OIDC, MFA, recovery.
45
+ - AuthZ: roles, ownership, tenancy, object-level checks.
46
+ - Input validation at every boundary.
47
+ - Output encoding and injection paths.
48
+ - Secrets: storage, rotation, least privilege, logs.
49
+ - Data: minimization, retention, encryption, backups.
50
+ - Supply chain: dependencies, lockfile, install scripts.
51
+ - Agent surface: untrusted content, tool permissions, prompt injection.
52
+
53
+ ### 3. Test the critical paths
54
+
55
+ - Authorization bypass: horizontal and vertical.
56
+ - IDOR, SSRF, injection, XSS, CSRF, path traversal.
57
+ - Session fixation, token leakage, insecure redirects.
58
+ - Rate limits, replay, idempotency.
59
+ - Secret exposure in logs, errors, screenshots, and repositories.
60
+
61
+ ### 4. Run the tools
62
+
63
+ Use what the project has; prefer local, open-source tools:
64
+
65
+ - SAST and lint rules;
66
+ - dependency audit;
67
+ - secret scanning (gitleaks or equivalent);
68
+ - container and configuration scanning;
69
+ - DAST or targeted requests for critical flows.
70
+
71
+ Tools find candidates; a human or agent must reproduce and explain them.
72
+
73
+ ### 5. Report with evidence
74
+
75
+ ```text
76
+ Finding:
77
+ Severity: critical | high | medium | low
78
+ Evidence: file:line + snippet | request/response | CVE link | screenshot
79
+ Impact:
80
+ Fix:
81
+ Verification:
82
+ ```
83
+
84
+ No finding without reproduction. No "probably vulnerable".
85
+
86
+ ### 6. Verify the fix
87
+
88
+ Re-run the failing request or test. Confirm the control works and does not break the
89
+ legitimate flow.
90
+
91
+ ## Output
92
+
93
+ `.companion/local/03-threat-model.md` during design and
94
+ `.companion/local/07-security-report.md` before release, with:
95
+
96
+ - assets, actors, entry points, trust boundaries;
97
+ - threats and controls;
98
+ - accepted risks with owner and date;
99
+ - findings with evidence and severity;
100
+ - tools and versions used;
101
+ - re-test results.
102
+
103
+ ## Verification
104
+
105
+ - Critical and high findings are closed or explicitly accepted.
106
+ - Every finding has reproducible evidence.
107
+ - Secrets were never printed or committed.
108
+ - Authz was tested with more than one role and more than one tenant.
109
+ - Dependency and container scans ran in the target version.
@@ -0,0 +1,109 @@
1
+ ---
2
+ name: test-strategy
3
+ description: Define how a project will be tested before development starts. Use before implementation, when planning a release, when a change affects critical flows, or when quality, load, accessibility, or security evidence must be agreed.
4
+ license: MIT
5
+ metadata:
6
+ version: "1.0.0"
7
+ author: development-companion
8
+ ---
9
+
10
+ # Test Strategy
11
+
12
+ QA enters before development. The test plan is the contract for what "working" means and
13
+ how it will be proven.
14
+
15
+ ## When to use
16
+
17
+ - Before implementing a feature or a new project.
18
+ - Before a release or a migration.
19
+ - When a defect escaped and the test strategy failed.
20
+ - When performance, accessibility, or security need explicit budgets.
21
+
22
+ ## Inputs
23
+
24
+ - Operational brief and acceptance criteria.
25
+ - Architecture, contracts, and threat model.
26
+ - Known failure modes and production incidents.
27
+ - Target environments and data constraints.
28
+
29
+ ## Procedure
30
+
31
+ ### 1. Map the risk
32
+
33
+ For each capability, ask:
34
+
35
+ - What happens if this fails?
36
+ - Who is affected, and how badly?
37
+ - Is it detectable, reversible, and recoverable?
38
+ - Is it a golden path, a dark path, or an edge case?
39
+
40
+ Prioritize tests by risk, not by ease.
41
+
42
+ ### 2. Enumerate paths
43
+
44
+ **Golden paths:** the flows that must work for the product to be useful.
45
+
46
+ **Dark paths:** invalid input, unauthorized access, expired sessions, network failure,
47
+ timeout, retry, partial failure, duplicate submission, empty state.
48
+
49
+ **Edge cases:** concurrency, idempotency, pagination, time zones, Unicode, large files,
50
+ rate limits, migrations, rollback, browser/platform differences.
51
+
52
+ ### 3. Choose levels
53
+
54
+ | Level | Proves |
55
+ |---|---|
56
+ | Unit | Domain rules and edge cases |
57
+ | Contract | API/schema compatibility |
58
+ | Integration | Real database, queues, third parties via fakes |
59
+ | E2E | Critical user journeys |
60
+ | Manual/visual | UX, accessibility, responsive, screenshots |
61
+ | Load/stress | Throughput, latency, saturation, recovery |
62
+ | Security | Authz, injection, secrets, dependencies |
63
+
64
+ Use the cheapest level that can prove the behavior. Do not mock the thing you are testing.
65
+
66
+ ### 4. Define evidence
67
+
68
+ For each must-pass behavior:
69
+
70
+ - exact command or manual step;
71
+ - expected observable result;
72
+ - artifact to keep: test output, request/response, screenshot, metric, log excerpt.
73
+
74
+ A test that cannot fail is not evidence.
75
+
76
+ ### 5. Plan environments and data
77
+
78
+ - Where tests run: local, CI, staging, target container.
79
+ - Seed data, fixtures, isolation, cleanup.
80
+ - Secrets: names only; never values in reports.
81
+ - Performance: environment specs, load profile, p95/p99, error rate, resources.
82
+
83
+ ### 6. Define exit criteria
84
+
85
+ - Which tests are must-pass.
86
+ - Which failures are acceptable and who accepts them.
87
+ - Which checks are skipped and why.
88
+ - What evidence is required for closure.
89
+
90
+ ## Output
91
+
92
+ `.companion/local/04-test-plan.md` with:
93
+
94
+ - risk matrix;
95
+ - golden, dark, and edge paths;
96
+ - test levels and tools;
97
+ - data and environments;
98
+ - load/stress scenario and budgets;
99
+ - accessibility and visual checks;
100
+ - security checks;
101
+ - evidence format;
102
+ - exit criteria.
103
+
104
+ ## Verification
105
+
106
+ - Every acceptance criterion maps to at least one test.
107
+ - Every critical dark path has a test or a documented reason.
108
+ - Load tests run in the target-like environment.
109
+ - The plan states how failures will be evidenced, not just detected.
@@ -0,0 +1,108 @@
1
+ ---
2
+ name: ux-design
3
+ description: Design and validate user flows, wireframes, states, responsiveness, motion, and accessibility before building UI. Use before frontend implementation, when the user provides sketches or references, or when visual approval is required.
4
+ license: MIT
5
+ metadata:
6
+ version: "1.0.0"
7
+ author: development-companion
8
+ ---
9
+
10
+ # UX Design
11
+
12
+ The user approves the experience before the team builds it. Design is validated with
13
+ flows, states, and screenshots, not with adjectives.
14
+
15
+ ## When to use
16
+
17
+ - A new screen, flow, or design system.
18
+ - A redesign or a responsive change.
19
+ - The user provides sketches, references, Figma frames, or vague visual expectations.
20
+ - Before frontend implementation starts.
21
+
22
+ ## Inputs
23
+
24
+ - Operational brief and target platforms.
25
+ - User personas, jobs, and success metrics.
26
+ - Brand or design system constraints.
27
+ - Accessibility requirements.
28
+
29
+ ## Procedure
30
+
31
+ ### 1. Map the flow
32
+
33
+ - Entry points, primary action, exit, and recovery.
34
+ - What the user sees before, during, and after.
35
+ - Decision points and failure branches.
36
+ - Permissions and empty states.
37
+
38
+ ### 2. Define states
39
+
40
+ Every screen must define:
41
+
42
+ - loading;
43
+ - empty;
44
+ - error with recovery;
45
+ - unauthorized or forbidden;
46
+ - offline or degraded;
47
+ - success and confirmation.
48
+
49
+ If a state is missing, the UI is incomplete.
50
+
51
+ ### 3. Choose layout and breakpoints
52
+
53
+ - Mobile-first or desktop-first, with a reason.
54
+ - Breakpoints and what changes at each.
55
+ - Touch targets, safe areas, keyboard navigation, zoom.
56
+ - Content hierarchy and scan path.
57
+
58
+ ### 4. Specify accessibility
59
+
60
+ - Semantic structure and landmarks.
61
+ - Labels, descriptions, and error association.
62
+ - Focus order, visible focus, and focus management.
63
+ - Contrast, motion, and `prefers-reduced-motion`.
64
+ - Screen reader announcements for async changes.
65
+
66
+ Target WCAG 2.2 AA unless the project states otherwise.
67
+
68
+ ### 5. Specify motion
69
+
70
+ - Purpose: orient, confirm, or explain.
71
+ - Duration and easing; no decorative motion that blocks work.
72
+ - Reduced-motion alternative.
73
+
74
+ ### 6. Produce mockups
75
+
76
+ Prefer local, reviewable artifacts:
77
+
78
+ - HTML/SVG wireframes in `.companion/local/mockups/`.
79
+ - Screenshots at desktop and mobile widths.
80
+ - Optional Figma integration via MCP when the user already works there. The CLI never
81
+ handles Figma tokens.
82
+
83
+ ### 7. Get approval
84
+
85
+ Present the flow, states, and screenshots. Ask for explicit approval or a concrete
86
+ change. Do not start implementation from an unapproved mockup.
87
+
88
+ ## Output
89
+
90
+ `.companion/local/05-ux-spec.md` with:
91
+
92
+ - flows and information architecture;
93
+ - screen inventory;
94
+ - states per screen;
95
+ - responsive behavior;
96
+ - accessibility checklist;
97
+ - motion specification;
98
+ - design tokens and components;
99
+ - mockup and screenshot references;
100
+ - approval record.
101
+
102
+ ## Verification
103
+
104
+ - All states are designed, not only the happy path.
105
+ - Keyboard and screen reader paths are described.
106
+ - Screenshots exist at desktop and mobile widths.
107
+ - The user approved the design or requested specific changes.
108
+ - A vision-capable model reviewed the screenshots against the spec.
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: windows-development
3
+ description: Build native Windows applications with WinUI, WPF, or Win32, including MSIX packaging, signing, permissions, and Windows integration. Use for Windows-specific desktop work.
4
+ license: MIT
5
+ metadata:
6
+ version: "1.0.0"
7
+ author: development-companion
8
+ ---
9
+
10
+ # Windows Development
11
+
12
+ Windows users expect native integration, predictable installers, and no surprise UAC
13
+ prompts. Build for the platform, not around it.
14
+
15
+ ## When to use
16
+
17
+ - A native Windows app or Windows-specific feature.
18
+ - MSIX/MSI packaging, signing, or Store submission.
19
+ - Registry, services, file associations, or shell integration.
20
+
21
+ ## Procedure
22
+
23
+ 1. **Choose the stack.** WinUI 3 for modern Windows apps; WPF for existing .NET desktop;
24
+ Win32 for low-level integration. Record the reason.
25
+ 2. **Design for the Windows lifecycle.** Single instance, activation, background tasks,
26
+ power/session events, and high-DPI/multi-monitor.
27
+ 3. **Respect permissions.** Avoid admin by default; use per-user install when possible.
28
+ Explain UAC prompts and least-privilege access.
29
+ 4. **Package properly.** MSIX preferred for modern distribution; document MSI or unpackaged
30
+ alternatives. Include uninstall and upgrade paths.
31
+ 5. **Sign artifacts.** Authenticode signing, timestamping, and SmartScreen reputation plan.
32
+ 6. **Integrate natively.** File dialogs, jump lists, notifications, taskbar, share, and
33
+ accessibility (UI Automation, Narrator, keyboard).
34
+ 7. **Handle data safely.** Use `%LOCALAPPDATA%`/`%APPDATA%`, atomic writes, and Credential
35
+ Manager or DPAPI for secrets.
36
+ 8. **Test on clean VMs.** Windows 10/11, different DPI, architectures, and no dev tools.
37
+
38
+ ## Verification
39
+
40
+ - Install, upgrade, repair, and uninstall tested on a clean Windows VM.
41
+ - Signed binaries; no unsigned update path.
42
+ - No admin requirement without justification.
43
+ - Accessibility and keyboard navigation verified.
44
+ - Crash reporting and update rollback tested.
45
+ - No secret in logs or crash dumps.
package/src/args.mjs ADDED
@@ -0,0 +1,42 @@
1
+ export function parseArgs(argv) {
2
+ const args = { _: [], flags: {} };
3
+ for (let i = 0; i < argv.length; i += 1) {
4
+ const item = argv[i];
5
+ if (!item.startsWith("--")) {
6
+ args._.push(item);
7
+ continue;
8
+ }
9
+ const [rawKey, inline] = item.slice(2).split("=", 2);
10
+ const key = rawKey.trim();
11
+ if (!key) continue;
12
+ if (inline !== undefined) {
13
+ args.flags[key] = inline;
14
+ continue;
15
+ }
16
+ const next = argv[i + 1];
17
+ if (next !== undefined && !next.startsWith("--")) {
18
+ args.flags[key] = next;
19
+ i += 1;
20
+ } else {
21
+ args.flags[key] = true;
22
+ }
23
+ }
24
+ return args;
25
+ }
26
+
27
+ export function flag(args, name, fallback = undefined) {
28
+ return Object.hasOwn(args.flags, name) ? args.flags[name] : fallback;
29
+ }
30
+
31
+ export function bool(args, name) {
32
+ return args.flags[name] === true || args.flags[name] === "true";
33
+ }
34
+
35
+ export function list(args, name) {
36
+ const value = flag(args, name);
37
+ if (!value || value === true) return [];
38
+ return String(value)
39
+ .split(",")
40
+ .map((item) => item.trim())
41
+ .filter(Boolean);
42
+ }