product-spec 0.2.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/CHANGELOG.md +49 -0
  2. package/LICENSE +21 -0
  3. package/README.md +152 -0
  4. package/assets/claude/commands/product-spec-align.md +37 -0
  5. package/assets/claude/commands/product-spec-domain.md +32 -0
  6. package/assets/claude/commands/product-spec-faq.md +34 -0
  7. package/assets/claude/commands/product-spec-press.md +31 -0
  8. package/assets/codex/commands/product-spec-align.md +25 -0
  9. package/assets/codex/commands/product-spec-domain.md +19 -0
  10. package/assets/codex/commands/product-spec-faq.md +22 -0
  11. package/assets/codex/commands/product-spec-press.md +19 -0
  12. package/assets/product/templates/domain-template.md +52 -0
  13. package/assets/product/templates/faq-template.md +38 -0
  14. package/assets/product/templates/press-template.md +26 -0
  15. package/assets/product/templates/requirements-template.md +34 -0
  16. package/dist/adapters/claude.d.ts +2 -0
  17. package/dist/adapters/claude.js +26 -0
  18. package/dist/adapters/claude.js.map +1 -0
  19. package/dist/adapters/codex.d.ts +2 -0
  20. package/dist/adapters/codex.js +26 -0
  21. package/dist/adapters/codex.js.map +1 -0
  22. package/dist/adapters/types.d.ts +12 -0
  23. package/dist/adapters/types.js +2 -0
  24. package/dist/adapters/types.js.map +1 -0
  25. package/dist/cli/commands/add.d.ts +6 -0
  26. package/dist/cli/commands/add.js +19 -0
  27. package/dist/cli/commands/add.js.map +1 -0
  28. package/dist/cli/commands/check.d.ts +4 -0
  29. package/dist/cli/commands/check.js +17 -0
  30. package/dist/cli/commands/check.js.map +1 -0
  31. package/dist/cli/commands/doctor.d.ts +4 -0
  32. package/dist/cli/commands/doctor.js +17 -0
  33. package/dist/cli/commands/doctor.js.map +1 -0
  34. package/dist/cli/commands/help.d.ts +2 -0
  35. package/dist/cli/commands/help.js +17 -0
  36. package/dist/cli/commands/help.js.map +1 -0
  37. package/dist/cli/commands/remove.d.ts +4 -0
  38. package/dist/cli/commands/remove.js +17 -0
  39. package/dist/cli/commands/remove.js.map +1 -0
  40. package/dist/cli/commands/targets.d.ts +2 -0
  41. package/dist/cli/commands/targets.js +9 -0
  42. package/dist/cli/commands/targets.js.map +1 -0
  43. package/dist/cli/commands/version.d.ts +2 -0
  44. package/dist/cli/commands/version.js +9 -0
  45. package/dist/cli/commands/version.js.map +1 -0
  46. package/dist/cli/main.d.ts +2 -0
  47. package/dist/cli/main.js +33 -0
  48. package/dist/cli/main.js.map +1 -0
  49. package/dist/cli/output/reporter.d.ts +6 -0
  50. package/dist/cli/output/reporter.js +38 -0
  51. package/dist/cli/output/reporter.js.map +1 -0
  52. package/dist/core/assets/registry.d.ts +11 -0
  53. package/dist/core/assets/registry.js +34 -0
  54. package/dist/core/assets/registry.js.map +1 -0
  55. package/dist/core/fs/project.d.ts +13 -0
  56. package/dist/core/fs/project.js +67 -0
  57. package/dist/core/fs/project.js.map +1 -0
  58. package/dist/core/orchestration/add.d.ts +8 -0
  59. package/dist/core/orchestration/add.js +63 -0
  60. package/dist/core/orchestration/add.js.map +1 -0
  61. package/dist/core/orchestration/check.d.ts +9 -0
  62. package/dist/core/orchestration/check.js +80 -0
  63. package/dist/core/orchestration/check.js.map +1 -0
  64. package/dist/core/orchestration/doctor.d.ts +9 -0
  65. package/dist/core/orchestration/doctor.js +18 -0
  66. package/dist/core/orchestration/doctor.js.map +1 -0
  67. package/dist/core/orchestration/remove.d.ts +6 -0
  68. package/dist/core/orchestration/remove.js +60 -0
  69. package/dist/core/orchestration/remove.js.map +1 -0
  70. package/dist/core/orchestration/shared-assets.d.ts +8 -0
  71. package/dist/core/orchestration/shared-assets.js +38 -0
  72. package/dist/core/orchestration/shared-assets.js.map +1 -0
  73. package/dist/core/orchestration/targets.d.ts +5 -0
  74. package/dist/core/orchestration/targets.js +19 -0
  75. package/dist/core/orchestration/targets.js.map +1 -0
  76. package/dist/core/state/manifest.d.ts +13 -0
  77. package/dist/core/state/manifest.js +91 -0
  78. package/dist/core/state/manifest.js.map +1 -0
  79. package/dist/types/index.d.ts +53 -0
  80. package/dist/types/index.js +2 -0
  81. package/dist/types/index.js.map +1 -0
  82. package/package.json +45 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,49 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ ## [Unreleased]
6
+
7
+ ### Changed
8
+
9
+ - Renamed the published package, CLI, assistant command prefix, and managed manifest path to `product-spec`
10
+ - Updated current-facing documentation, CLI help text, and packaged assistant assets to use `product-spec`
11
+ - Updated current-facing repository guidance to use the `product-spec` name consistently
12
+
13
+ ## [0.2.0] - 2026-03-29
14
+
15
+ ### Added
16
+
17
+ - TypeScript-based `product-spec` CLI scaffolding with `add`, `remove`, `check`, `doctor`, `help`, and `version`
18
+ - Claude Code and Codex adapter structure with manifest-based ownership tracking
19
+ - Versioned `assets/` tree for `/product-spec-*` assistant commands and shared `.product` templates
20
+ - Vitest-based unit and integration coverage for manifest and CLI lifecycle flows
21
+ - GitHub Actions for CI and tag-driven release publishing to GitHub Releases and npm
22
+
23
+ ### Changed
24
+
25
+ - README now documents npm-first installation and direct `npx` execution for the `product-spec` CLI
26
+ - `.npmignore` and package metadata prepared for npm distribution
27
+ - npm package name is now `product-spec`
28
+
29
+ ### Removed
30
+
31
+ - Legacy `install.sh` installer
32
+ - Legacy tracked `/pm-*` Claude command files from the repository root command set
33
+
34
+ ## [2026-03-29]
35
+
36
+ ### Added
37
+
38
+ - Feature specification, implementation plan, research, data model, CLI contract, quickstart, and task breakdown for the prime-time CLI and multi-agent release
39
+ - Repository `.gitignore` cleanup for editor files, temp files, local agent directories, and generated local state
40
+ - README status update describing current behavior and planned next-version direction
41
+ - Initial `CHANGELOG.md`
42
+
43
+ ## [2026-03-28]
44
+
45
+ ### Added
46
+
47
+ - Initial product-spec command set: `/pm-domain`, `/pm-press`, `/pm-faq`, and `/pm-align`
48
+ - Product document templates for domain, press, FAQ, and requirements
49
+ - Shell-based installer and README reorganization for the current Claude Code workflow
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ehud
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,152 @@
1
+ # product-spec
2
+
3
+ The product management counterpart to [spec-kit](https://github.com/github/spec-kit). product-spec brings product management disciplines to spec-driven development, following Amazon's Working Backwards (PR/FAQ) methodology.
4
+
5
+ While spec-kit handles engineering specifications, product-spec handles the product narrative: the domain context, press releases, FAQs, and requirements that define what you're building and why before spec-kit defines how.
6
+
7
+ ## Installation
8
+
9
+ ### Recommended: install globally from npm
10
+
11
+ ```sh
12
+ npm install -g product-spec
13
+ ```
14
+
15
+ Then inside any project:
16
+
17
+ ```sh
18
+ product-spec add claude
19
+ product-spec add codex
20
+ product-spec add both
21
+ product-spec check both
22
+ ```
23
+
24
+ ### Option 2: run directly without a global install
25
+
26
+ ```sh
27
+ npx --yes --package product-spec product-spec add claude
28
+ ```
29
+
30
+ Use the same pattern for other commands:
31
+
32
+ ```sh
33
+ npx --yes --package product-spec product-spec check both
34
+ ```
35
+
36
+ ### Option 3: install from GitHub source
37
+
38
+ This is the least recommended path, but it is useful when testing unpublished changes:
39
+
40
+ ```sh
41
+ npm install -g github:ehud-am/product-spec
42
+ ```
43
+
44
+ ## CLI Usage
45
+
46
+ Project integration commands:
47
+
48
+ ```text
49
+ product-spec add claude
50
+ product-spec add codex
51
+ product-spec add both
52
+ product-spec remove claude
53
+ product-spec remove codex
54
+ product-spec remove both
55
+ product-spec check both
56
+ product-spec doctor both
57
+ product-spec version
58
+ product-spec help
59
+ ```
60
+
61
+ | Command | Purpose |
62
+ |---------|---------|
63
+ | `product-spec add <target>` | Add product-spec-managed assistant commands and shared templates to the current project |
64
+ | `product-spec remove <target>` | Remove only product-spec-managed files for the selected target |
65
+ | `product-spec check [target]` | Validate that managed integrations are present and healthy |
66
+ | `product-spec doctor [target]` | Show richer diagnostics and recovery guidance |
67
+ | `product-spec version` | Print the installed CLI version |
68
+ | `product-spec help` | Show command help and examples |
69
+
70
+ ## Assistant Commands
71
+
72
+ After adding an integration, use the installed slash commands inside the assistant:
73
+
74
+ ```text
75
+ /product-spec-domain ...
76
+ /product-spec-press ...
77
+ /product-spec-faq
78
+ /product-spec-align
79
+ ```
80
+
81
+ | Target | Command directory | Slash commands |
82
+ |--------|-------------------|----------------|
83
+ | Claude Code | `.claude/commands/` | `/product-spec-domain`, `/product-spec-press`, `/product-spec-faq`, `/product-spec-align` |
84
+ | Codex | `.Codex/commands/` | `/product-spec-domain`, `/product-spec-press`, `/product-spec-faq`, `/product-spec-align` |
85
+
86
+ ## How It Works
87
+
88
+ product-spec creates a `.product/` folder in your project that maintains a living, cumulative view of the product across releases. Each document grows over time, telling the full story of the project from its first release to the one currently under development.
89
+
90
+ ### Documents
91
+
92
+ | File | Purpose |
93
+ |------|---------|
94
+ | `.product/domain.md` | Industry context, target users, terminology, competitive landscape |
95
+ | `.product/press.md` | Press releases for every release, upcoming first and historical below |
96
+ | `.product/faq.md` | External and internal FAQs for every release, upcoming first and historical below |
97
+ | `.product/requirements.md` | Release-independent, complete view of all product use cases and capabilities |
98
+
99
+ ### Workflow
100
+
101
+ ```text
102
+ /product-spec-domain --> /product-spec-press --> /product-spec-faq --> /speckit.specify --> /product-spec-align
103
+ (context) (promise) (challenge) (engineer) (reconcile)
104
+ ```
105
+
106
+ 1. `/product-spec-domain` establishes the domain context: who the users are, what problem matters, and who the alternatives are.
107
+ 2. `/product-spec-press` writes a press release as if the next release has already shipped.
108
+ 3. `/product-spec-faq` challenges the press release with hard questions from customers and stakeholders.
109
+ 4. `/speckit.specify` hands off to spec-kit for engineering specifications.
110
+ 5. `/product-spec-align` reconciles product docs with the final engineering scope.
111
+
112
+ ## Key Concepts
113
+
114
+ ### Cumulative Documents
115
+
116
+ Unlike traditional release notes, product-spec documents are cumulative. The press release file contains all press releases ever written for the project, with the upcoming release at the top and historical releases below. The same applies to FAQs.
117
+
118
+ ### `requirements.md` as the Product Spec
119
+
120
+ While `press.md` and `faq.md` are organized by release, `requirements.md` is organized by functional area. It is the release-independent, always-current answer to "what does this product do?"
121
+
122
+ ### Working Backwards
123
+
124
+ The methodology is Amazon's PR/FAQ approach:
125
+ - start with the customer experience, not the technical solution
126
+ - force hard questions early before committing engineering resources
127
+ - treat the press release as a contract for value, clarity, and scope
128
+
129
+ ## Release and Publishing
130
+
131
+ GitHub Actions now handles:
132
+ - CI validation on pushes and pull requests
133
+ - packaging tagged releases
134
+ - publishing the npm package when a `v*` tag is pushed
135
+
136
+ ## Rename Notes
137
+
138
+ `product-spec` is now the canonical package name, CLI name, assistant command prefix, and project-local manifest path.
139
+
140
+ ## Requirements
141
+
142
+ - Node.js and npm
143
+ - [Claude Code](https://claude.ai/code) and/or Codex for assistant integration targets
144
+ - [spec-kit](https://github.com/github/spec-kit) for the `/speckit.specify` portion of the workflow
145
+
146
+ ## Changelog
147
+
148
+ Project history lives in [CHANGELOG.md](CHANGELOG.md).
149
+
150
+ ## License
151
+
152
+ MIT
@@ -0,0 +1,37 @@
1
+ ---
2
+ description: Reconcile the .product folder with changes made in .specify specs — update press, faq, and requirements.
3
+ handoffs:
4
+ - label: Update Press Release
5
+ agent: product-spec-press
6
+ prompt: Refine the press release based on alignment findings
7
+ - label: Update FAQs
8
+ agent: product-spec-faq
9
+ prompt: Update the FAQs based on alignment findings
10
+ - label: Update Domain
11
+ agent: product-spec-domain
12
+ prompt: Update domain knowledge based on what we learned during alignment
13
+ ---
14
+
15
+ ## User Input
16
+
17
+ ```text
18
+ $ARGUMENTS
19
+ ```
20
+
21
+ You **MUST** consider the user input before proceeding (if not empty).
22
+
23
+ ## Outline
24
+
25
+ You are reconciling the product documents in `.product/` with the engineering specifications in `.specify/`.
26
+
27
+ ### Pre-Execution
28
+
29
+ 1. Load `.product/domain.md`, `.product/press.md`, `.product/faq.md`, and `.product/requirements.md` when present.
30
+ 2. Discover all `spec.md` files under `.specify/`.
31
+ 3. Use `.product/templates/requirements-template.md` if `requirements.md` does not yet exist.
32
+
33
+ ### Execution Flow
34
+
35
+ 1. Compare press release promises against the actual engineering specs.
36
+ 2. Update FAQs and requirements to reflect reality.
37
+ 3. Preserve historical product narrative and produce an alignment report.
@@ -0,0 +1,32 @@
1
+ ---
2
+ description: Provide domain knowledge as background context for the project.
3
+ handoffs:
4
+ - label: Write Press Release
5
+ agent: product-spec-press
6
+ prompt: Write the press release for the next release
7
+ ---
8
+
9
+ ## User Input
10
+
11
+ ```text
12
+ $ARGUMENTS
13
+ ```
14
+
15
+ You **MUST** consider the user input before proceeding (if not empty).
16
+
17
+ ## Outline
18
+
19
+ You are creating or updating the domain knowledge document at `.product/domain.md`. This document captures the industry context, problem space, target users, terminology, and competitive landscape that inform all product decisions.
20
+
21
+ ### Pre-Execution
22
+
23
+ 1. **Ensure `.product/` exists**: If the `.product/` directory does not exist, create it.
24
+ 2. **Check for existing domain doc**: Read `.product/domain.md` if it exists.
25
+ - If it exists and has content beyond the template, this is an **update** — preserve existing content and merge new information.
26
+ - If it does not exist, load `.product/templates/domain-template.md` as the starting structure.
27
+
28
+ ### Execution Flow
29
+
30
+ 1. **Parse user input**: The text after `/product-spec-domain` is the domain context the user wants to capture.
31
+ 2. Create or update `.product/domain.md` using the same quality checks and guidelines as the existing product-spec domain workflow.
32
+ 3. Suggest `/product-spec-press` as the next step when appropriate.
@@ -0,0 +1,34 @@
1
+ ---
2
+ description: Create or update FAQs that challenge and support the press release claims.
3
+ handoffs:
4
+ - label: Update Press Release
5
+ agent: product-spec-press
6
+ prompt: Update the press release based on what we learned from the FAQs
7
+ - label: Build Specification
8
+ agent: speckit.specify
9
+ prompt: Create a technical spec for the next feature. I want to build...
10
+ ---
11
+
12
+ ## User Input
13
+
14
+ ```text
15
+ $ARGUMENTS
16
+ ```
17
+
18
+ You **MUST** consider the user input before proceeding (if not empty).
19
+
20
+ ## Outline
21
+
22
+ You are creating or updating the FAQ document at `.product/faq.md`.
23
+
24
+ ### Pre-Execution
25
+
26
+ 1. Ensure `.product/` exists.
27
+ 2. Load `.product/domain.md` and `.product/press.md` when available.
28
+ 3. If `.product/faq.md` is missing, start from `.product/templates/faq-template.md`.
29
+
30
+ ### Execution Flow
31
+
32
+ 1. The text after `/product-spec-faq` describes what to generate or update.
33
+ 2. Produce external and internal FAQs that challenge the current press release honestly.
34
+ 3. Preserve historical FAQ sections and suggest `/speckit.specify` when the feature is ready for engineering.
@@ -0,0 +1,31 @@
1
+ ---
2
+ description: Provide the press release for the project following Amazon's Working Backwards methodology.
3
+ handoffs:
4
+ - label: Write FAQs
5
+ agent: product-spec-faq
6
+ prompt: Write the FAQs that challenge this press release
7
+ ---
8
+
9
+ ## User Input
10
+
11
+ ```text
12
+ $ARGUMENTS
13
+ ```
14
+
15
+ You **MUST** consider the user input before proceeding (if not empty).
16
+
17
+ ## Outline
18
+
19
+ You are creating or updating the press release document at `.product/press.md`.
20
+
21
+ ### Pre-Execution
22
+
23
+ 1. Ensure `.product/` exists.
24
+ 2. Load `.product/domain.md` if it exists.
25
+ 3. Read `.product/press.md` if it exists; otherwise use `.product/templates/press-template.md`.
26
+
27
+ ### Execution Flow
28
+
29
+ 1. The text after `/product-spec-press` describes what to write.
30
+ 2. Create or update the current upcoming press release using Amazon's Working Backwards format.
31
+ 3. Preserve historical entries and suggest `/product-spec-faq` when appropriate.
@@ -0,0 +1,25 @@
1
+ ---
2
+ description: Reconcile the .product folder with changes made in .specify specs — update press, faq, and requirements.
3
+ handoffs:
4
+ - label: Update Press Release
5
+ agent: product-spec-press
6
+ prompt: Refine the press release based on alignment findings
7
+ - label: Update FAQs
8
+ agent: product-spec-faq
9
+ prompt: Update the FAQs based on alignment findings
10
+ - label: Update Domain
11
+ agent: product-spec-domain
12
+ prompt: Update domain knowledge based on what we learned during alignment
13
+ ---
14
+
15
+ ## User Input
16
+
17
+ ```text
18
+ $ARGUMENTS
19
+ ```
20
+
21
+ You **MUST** consider the user input before proceeding (if not empty).
22
+
23
+ ## Outline
24
+
25
+ You are reconciling `.product/` with `.specify/` specs so product-facing documents stay aligned with the engineering scope.
@@ -0,0 +1,19 @@
1
+ ---
2
+ description: Provide domain knowledge as background context for the project.
3
+ handoffs:
4
+ - label: Write Press Release
5
+ agent: product-spec-press
6
+ prompt: Write the press release for the next release
7
+ ---
8
+
9
+ ## User Input
10
+
11
+ ```text
12
+ $ARGUMENTS
13
+ ```
14
+
15
+ You **MUST** consider the user input before proceeding (if not empty).
16
+
17
+ ## Outline
18
+
19
+ You are creating or updating the domain knowledge document at `.product/domain.md`. This document captures the industry context, problem space, target users, terminology, and competitive landscape that inform all product decisions.
@@ -0,0 +1,22 @@
1
+ ---
2
+ description: Create or update FAQs that challenge and support the press release claims.
3
+ handoffs:
4
+ - label: Update Press Release
5
+ agent: product-spec-press
6
+ prompt: Update the press release based on what we learned from the FAQs
7
+ - label: Build Specification
8
+ agent: speckit.specify
9
+ prompt: Create a technical spec for the next feature. I want to build...
10
+ ---
11
+
12
+ ## User Input
13
+
14
+ ```text
15
+ $ARGUMENTS
16
+ ```
17
+
18
+ You **MUST** consider the user input before proceeding (if not empty).
19
+
20
+ ## Outline
21
+
22
+ You are creating or updating the FAQ document at `.product/faq.md`, generating honest external and internal questions that stress-test the current press release.
@@ -0,0 +1,19 @@
1
+ ---
2
+ description: Provide the press release for the project following Amazon's Working Backwards methodology.
3
+ handoffs:
4
+ - label: Write FAQs
5
+ agent: product-spec-faq
6
+ prompt: Write the FAQs that challenge this press release
7
+ ---
8
+
9
+ ## User Input
10
+
11
+ ```text
12
+ $ARGUMENTS
13
+ ```
14
+
15
+ You **MUST** consider the user input before proceeding (if not empty).
16
+
17
+ ## Outline
18
+
19
+ You are creating or updating the press release document at `.product/press.md`, preserving historical entries and writing from the customer's point of view.
@@ -0,0 +1,52 @@
1
+ # Domain Knowledge: [PROJECT_NAME]
2
+
3
+ **Last Updated**: [DATE]
4
+
5
+ ## Industry Context
6
+
7
+ [Describe the industry or market this project operates in. What is the broader landscape? Who are the key players? What trends are shaping this space?]
8
+
9
+ ## Problem Space
10
+
11
+ [What fundamental problem does this project address? Why does this problem matter? Who experiences this problem most acutely?]
12
+
13
+ ## Target Users
14
+
15
+ ### Primary Users
16
+
17
+ - **[Persona 1]**: [Role, goals, pain points, and how they relate to this project]
18
+ - **[Persona 2]**: [Role, goals, pain points, and how they relate to this project]
19
+
20
+ ### Secondary Users
21
+
22
+ - **[Persona 3]**: [Role, goals, and indirect relationship to the project]
23
+
24
+ ## Key Concepts & Terminology
25
+
26
+ | Term | Definition |
27
+ |------|-----------|
28
+ | [Term 1] | [Clear, concise definition as used in this project's context] |
29
+ | [Term 2] | [Clear, concise definition as used in this project's context] |
30
+ | [Term 3] | [Clear, concise definition as used in this project's context] |
31
+
32
+ ## Competitive Landscape
33
+
34
+ | Competitor / Alternative | Approach | Strengths | Weaknesses |
35
+ |--------------------------|----------|-----------|------------|
36
+ | [Competitor 1] | [How they solve the problem] | [What they do well] | [Where they fall short] |
37
+ | [Competitor 2] | [How they solve the problem] | [What they do well] | [Where they fall short] |
38
+ | [Status quo / manual process] | [How people cope today] | [Why they stick with it] | [Cost of not changing] |
39
+
40
+ ## Constraints & Regulations
41
+
42
+ - [Industry regulation, compliance requirement, or technical constraint that shapes product decisions]
43
+ - [Market expectation or standard that must be met]
44
+
45
+ ## Key Metrics & Success Indicators
46
+
47
+ - [How success is measured in this domain — e.g., adoption rate, time-to-value, retention]
48
+ - [Industry benchmarks or standards to aim for]
49
+
50
+ ## Open Questions
51
+
52
+ - [Unresolved domain questions that may affect product direction]
@@ -0,0 +1,38 @@
1
+ # Frequently Asked Questions: [PROJECT_NAME]
2
+
3
+ **Last Updated**: [DATE]
4
+
5
+ ---
6
+
7
+ ## [RELEASE_NAME] — [TARGET_DATE] *(upcoming)*
8
+
9
+ ### External FAQs (Customer-Facing)
10
+
11
+ **Q: [Question a customer would ask after reading the press release]**
12
+ A: [Clear, honest answer. No jargon. If the answer is "not yet," say so and explain the plan.]
13
+
14
+ **Q: [Question about pricing, availability, or getting started]**
15
+ A: [Direct answer with specifics where possible.]
16
+
17
+ **Q: [Question about how this compares to alternatives]**
18
+ A: [Honest comparison. Acknowledge competitor strengths. Explain your differentiation.]
19
+
20
+ **Q: [Question about limitations or edge cases]**
21
+ A: [Transparent answer about what the product does NOT do and why.]
22
+
23
+ ### Internal FAQs (Stakeholder-Facing)
24
+
25
+ **Q: [Question about feasibility — "Can we actually build this?"]**
26
+ A: [Technical assessment. What's proven vs. what's risky? What needs prototyping?]
27
+
28
+ **Q: [Question about scope — "Why not also do X?"]**
29
+ A: [Explain the scoping decision. What's deferred and why? What's the cost of adding it?]
30
+
31
+ **Q: [Question about metrics — "How will we know this is working?"]**
32
+ A: [Specific metrics, measurement approach, and success thresholds.]
33
+
34
+ **Q: [Question about dependencies or risks]**
35
+ A: [Identify dependencies, risks, and mitigation strategies.]
36
+
37
+ **Q: [Question about timeline or resources]**
38
+ A: [Honest assessment of what it takes to deliver.]
@@ -0,0 +1,26 @@
1
+ # Press Releases: [PROJECT_NAME]
2
+
3
+ <!--
4
+ This document contains all press releases for this project, ordered reverse-chronologically.
5
+ -->
6
+
7
+ ---
8
+
9
+ ## [RELEASE_NAME] — [TARGET_DATE] *(upcoming)*
10
+
11
+ **[CITY, STATE]** — [One-sentence opening that names the customer segment and the key benefit they now have. This is the hook.]
12
+
13
+ [Second paragraph: What is the problem customers faced? Why was it painful or costly? Set up the "before" state in 2-3 sentences.]
14
+
15
+ [Third paragraph: What does the product/feature do? Describe it in customer terms — what they can now do that they couldn't before. No implementation details. Keep it to 3-4 sentences.]
16
+
17
+ > "[Customer quote expressing delight about how this changes their workflow/life. Should feel authentic, specific, and human.]"
18
+ > — [Customer Name], [Title], [Company/Context]
19
+
20
+ [Fourth paragraph: How to get started. What does a customer do next? One clear call to action.]
21
+
22
+ ### Key Benefits
23
+
24
+ - **[Benefit 1]**: [One sentence explaining the customer value]
25
+ - **[Benefit 2]**: [One sentence explaining the customer value]
26
+ - **[Benefit 3]**: [One sentence explaining the customer value]
@@ -0,0 +1,34 @@
1
+ # Product Requirements: [PROJECT_NAME]
2
+
3
+ **Last Updated**: [DATE]
4
+
5
+ ## Product Overview
6
+
7
+ [2-3 sentences describing what the product does, who it's for, and the core value proposition.]
8
+
9
+ ## Use Cases
10
+
11
+ ### UC-001: [Use Case Name]
12
+
13
+ - **Actor**: [Who performs this]
14
+ - **Goal**: [What they want to accomplish]
15
+ - **Description**: [How the product supports this goal, end to end]
16
+ - **Status**: [Complete | Partial | Planned]
17
+
18
+ ## Functional Summary
19
+
20
+ ### [Functional Area 1]
21
+
22
+ | Capability | Description | Status |
23
+ |-----------|-------------|--------|
24
+ | [Capability] | [What it does from the user's perspective] | [Shipped / In Progress / Planned] |
25
+
26
+ ## Cross-Cutting Concerns
27
+
28
+ - **[Concern]**: [How it's handled across the product]
29
+
30
+ ## Changelog
31
+
32
+ | Date | Change | Source |
33
+ |------|--------|--------|
34
+ | [DATE] | [What changed in this document] | [Which spec or release triggered the update] |
@@ -0,0 +1,2 @@
1
+ import type { AssistantAdapter } from "./types.js";
2
+ export declare const claudeAdapter: AssistantAdapter;
@@ -0,0 +1,26 @@
1
+ import { joinProjectPath, pathExists } from "../core/fs/project.js";
2
+ async function describeHealthIssues(context) {
3
+ const issues = [];
4
+ for (const asset of context.targetAssets) {
5
+ const absolutePath = joinProjectPath(context.rootDir, asset.targetPath);
6
+ if (!(await pathExists(absolutePath))) {
7
+ issues.push({
8
+ code: "CLAUDE_MISSING_FILE",
9
+ severity: "error",
10
+ message: `Missing Claude Code asset ${asset.targetPath}`,
11
+ path: asset.targetPath
12
+ });
13
+ }
14
+ }
15
+ return issues;
16
+ }
17
+ export const claudeAdapter = {
18
+ key: "claude",
19
+ displayName: "Claude Code",
20
+ commandDir: ".claude/commands",
21
+ resolveCommandTarget(fileName) {
22
+ return `.claude/commands/${fileName}`;
23
+ },
24
+ describeHealthIssues
25
+ };
26
+ //# sourceMappingURL=claude.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEpE,KAAK,UAAU,oBAAoB,CAAC,OAA6B;IAC/D,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzC,MAAM,YAAY,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QACxE,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;YACtC,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,qBAAqB;gBAC3B,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,6BAA6B,KAAK,CAAC,UAAU,EAAE;gBACxD,IAAI,EAAE,KAAK,CAAC,UAAU;aACvB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAqB;IAC7C,GAAG,EAAE,QAAQ;IACb,WAAW,EAAE,aAAa;IAC1B,UAAU,EAAE,kBAAkB;IAC9B,oBAAoB,CAAC,QAAgB;QACnC,OAAO,oBAAoB,QAAQ,EAAE,CAAC;IACxC,CAAC;IACD,oBAAoB;CACrB,CAAC"}
@@ -0,0 +1,2 @@
1
+ import type { AssistantAdapter } from "./types.js";
2
+ export declare const codexAdapter: AssistantAdapter;
@@ -0,0 +1,26 @@
1
+ import { joinProjectPath, pathExists } from "../core/fs/project.js";
2
+ async function describeHealthIssues(context) {
3
+ const issues = [];
4
+ for (const asset of context.targetAssets) {
5
+ const absolutePath = joinProjectPath(context.rootDir, asset.targetPath);
6
+ if (!(await pathExists(absolutePath))) {
7
+ issues.push({
8
+ code: "CODEX_MISSING_FILE",
9
+ severity: "error",
10
+ message: `Missing Codex asset ${asset.targetPath}`,
11
+ path: asset.targetPath
12
+ });
13
+ }
14
+ }
15
+ return issues;
16
+ }
17
+ export const codexAdapter = {
18
+ key: "codex",
19
+ displayName: "Codex",
20
+ commandDir: ".Codex/commands",
21
+ resolveCommandTarget(fileName) {
22
+ return `.Codex/commands/${fileName}`;
23
+ },
24
+ describeHealthIssues
25
+ };
26
+ //# sourceMappingURL=codex.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"codex.js","sourceRoot":"","sources":["../../src/adapters/codex.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEpE,KAAK,UAAU,oBAAoB,CAAC,OAA6B;IAC/D,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzC,MAAM,YAAY,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QACxE,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;YACtC,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,oBAAoB;gBAC1B,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,uBAAuB,KAAK,CAAC,UAAU,EAAE;gBAClD,IAAI,EAAE,KAAK,CAAC,UAAU;aACvB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAqB;IAC5C,GAAG,EAAE,OAAO;IACZ,WAAW,EAAE,OAAO;IACpB,UAAU,EAAE,iBAAiB;IAC7B,oBAAoB,CAAC,QAAgB;QACnC,OAAO,mBAAmB,QAAQ,EAAE,CAAC;IACvC,CAAC;IACD,oBAAoB;CACrB,CAAC"}