@fission-ai/openspec 0.1.0

package/dist/core/templates/claude-template.js

@@ -0,0 +1,96 @@
+export const claudeTemplate = `# OpenSpec Project
+
+This project uses OpenSpec for spec-driven development. Specifications are the source of truth.
+
+See @openspec/README.md for detailed conventions and guidelines.
+
+## Three-Stage Workflow
+
+### Stage 1: Creating Changes
+Create proposal for: features, breaking changes, architecture changes
+Skip proposal for: bug fixes, typos, non-breaking updates
+
+### Stage 2: Implementing Changes
+1. Read proposal.md to understand the change
+2. Read design.md if it exists for technical context
+3. Read tasks.md for implementation checklist
+4. Complete tasks one by one
+5. Mark each task complete immediately: \`- [x]\`
+
+### Stage 3: Archiving
+After deployment, use \`openspec archive [change]\` (add \`--skip-specs\` for tooling-only changes)
+
+## Before Any Task
+
+**Always:**
+- Check existing specs: \`openspec list --specs\`
+- Check active changes: \`openspec list\`
+- Read relevant specs before creating new ones
+- Prefer modifying existing specs over creating duplicates
+
+## CLI Quick Reference
+
+\`\`\`bash
+# Essential
+openspec list              # Active changes
+openspec list --specs      # Existing specifications
+openspec show [item]       # View details
+openspec diff [change]     # Show spec differences
+openspec validate --strict # Validate thoroughly
+openspec archive [change]  # Archive after deployment
+
+# Interactive
+openspec show              # Prompts for selection
+openspec validate          # Bulk validation
+
+# Debugging
+openspec show [change] --json --deltas-only
+\`\`\`
+
+## Creating Changes
+
+1. **Directory:** \`changes/[descriptive-name]/\`
+2. **Files:**
+   - \`proposal.md\` - Why, what, impact
+   - \`tasks.md\` - Implementation checklist
+   - \`specs/[capability]/spec.md\` - Delta changes (ADDED/MODIFIED/REMOVED)
+
+## Critical: Scenario Format
+
+**CORRECT:**
+\`\`\`markdown
+#### Scenario: User login
+- **WHEN** valid credentials
+- **THEN** return token
+\`\`\`
+
+**WRONG:** Using bullets (- **Scenario**), bold (**Scenario:**), or ### headers
+
+Every requirement MUST have scenarios using \`#### Scenario:\` format.
+
+## Complexity Management
+
+**Default to minimal:**
+- <100 lines of new code
+- Single-file implementations
+- No frameworks without justification
+- Boring, proven patterns
+
+**Only add complexity with:**
+- Performance data showing need
+- Concrete scale requirements (>1000 users)
+- Multiple proven use cases
+
+## Troubleshooting
+
+**"Change must have at least one delta"**
+- Check \`changes/[name]/specs/\` exists
+- Verify operation prefixes (## ADDED Requirements)
+
+**"Requirement must have at least one scenario"**
+- Use \`#### Scenario:\` format (4 hashtags)
+- Don't use bullets or bold
+
+**Debug:** \`openspec show [change] --json --deltas-only\`
+`;
+//# sourceMappingURL=claude-template.js.map

package/dist/core/templates/index.d.ts

@@ -0,0 +1,11 @@
+import { ProjectContext } from './project-template.js';
+export interface Template {
+    path: string;
+    content: string | ((context: ProjectContext) => string);
+}
+export declare class TemplateManager {
+    static getTemplates(context?: ProjectContext): Template[];
+    static getClaudeTemplate(): string;
+}
+export { ProjectContext } from './project-template.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/templates/index.js

@@ -0,0 +1,21 @@
+import { readmeTemplate } from './readme-template.js';
+import { projectTemplate } from './project-template.js';
+import { claudeTemplate } from './claude-template.js';
+export class TemplateManager {
+    static getTemplates(context = {}) {
+        return [
+            {
+                path: 'README.md',
+                content: readmeTemplate
+            },
+            {
+                path: 'project.md',
+                content: projectTemplate(context)
+            }
+        ];
+    }
+    static getClaudeTemplate() {
+        return claudeTemplate;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/core/templates/project-template.d.ts

@@ -0,0 +1,8 @@
+export interface ProjectContext {
+    projectName?: string;
+    description?: string;
+    techStack?: string[];
+    conventions?: string;
+}
+export declare const projectTemplate: (context?: ProjectContext) => string;
+//# sourceMappingURL=project-template.d.ts.map

package/dist/core/templates/project-template.js

@@ -0,0 +1,32 @@
+export const projectTemplate = (context = {}) => `# ${context.projectName || 'Project'} Context
+
+## Purpose
+${context.description || '[Describe your project\'s purpose and goals]'}
+
+## Tech Stack
+${context.techStack?.length ? context.techStack.map(tech => `- ${tech}`).join('\n') : '- [List your primary technologies]\n- [e.g., TypeScript, React, Node.js]'}
+
+## Project Conventions
+
+### Code Style
+[Describe your code style preferences, formatting rules, and naming conventions]
+
+### Architecture Patterns
+[Document your architectural decisions and patterns]
+
+### Testing Strategy
+[Explain your testing approach and requirements]
+
+### Git Workflow
+[Describe your branching strategy and commit conventions]
+
+## Domain Context
+[Add domain-specific knowledge that AI assistants need to understand]
+
+## Important Constraints
+[List any technical, business, or regulatory constraints]
+
+## External Dependencies
+[Document key external services, APIs, or systems]
+`;
+//# sourceMappingURL=project-template.js.map

package/dist/core/templates/readme-template.d.ts

@@ -0,0 +1,2 @@
+export declare const readmeTemplate = "# OpenSpec Instructions\n\nThis document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects.\n\n## Core Principle\n\nOpenSpec is an AI-native system for change-driven development where:\n- **Specs** (`specs/`) reflect what IS currently built and deployed\n- **Changes** (`changes/`) contain proposals for what SHOULD be changed\n- **AI drives the process** - You generate proposals, humans review and approve\n- **Specs are living documentation** - Always kept in sync with deployed code\n\n## Start Simple\n\n**Default to minimal implementations:**\n- New features should be <100 lines of code initially\n- Use the simplest solution that works\n- Avoid premature optimization (no caching, parallelization, or complex patterns without proven need)\n- Choose boring technology over cutting-edge solutions\n\n**Complexity triggers** - Only add complexity when you have:\n- **Performance data** showing current solution is too slow\n- **Scale requirements** with specific numbers (>1000 users, >100MB data)\n- **Multiple use cases** requiring the same abstraction\n- **Regulatory compliance** mandating specific patterns\n- **Security threats** that simple solutions cannot address\n\nWhen triggered, document the specific justification in your change proposal.\n\n## Directory Structure\n\n```\nopenspec/\n\u251C\u2500\u2500 project.md              # Project-specific context (tech stack, conventions)\n\u251C\u2500\u2500 README.md               # This file - OpenSpec instructions\n\u251C\u2500\u2500 specs/                  # Current truth - what IS built\n\u2502   \u251C\u2500\u2500 [capability]/       # Single, focused capability\n\u2502   \u2502   \u251C\u2500\u2500 spec.md         # WHAT the capability does and WHY\n\u2502   \u2502   \u2514\u2500\u2500 design.md       # HOW it's built (established patterns)\n\u2502   \u2514\u2500\u2500 ...\n\u251C\u2500\u2500 changes/                # Proposed changes - what we're CHANGING\n\u2502   \u251C\u2500\u2500 [change-name]/\n\u2502   \u2502   \u251C\u2500\u2500 proposal.md     # Why, what, impact (consolidated)\n\u2502   \u2502   \u251C\u2500\u2500 tasks.md        # Implementation checklist\n\u2502   \u2502   \u251C\u2500\u2500 design.md       # Technical decisions (optional, for complex changes)\n\u2502   \u2502   \u2514\u2500\u2500 specs/          # Delta changes to specs\n\u2502   \u2502       \u2514\u2500\u2500 [capability]/\n\u2502   \u2502           \u2514\u2500\u2500 spec.md # Delta format (ADDED/MODIFIED/REMOVED/RENAMED)\n\u2502   \u2514\u2500\u2500 archive/            # Completed changes (dated)\n```\n\n### Capability Organization\n\n**Use capabilities, not features** - Each directory under `specs/` represents a single, focused responsibility:\n- **Verb-noun naming**: `user-auth`, `payment-capture`, `order-checkout`\n- **10-minute rule**: Each capability should be understandable in <10 minutes\n- **Single purpose**: If it needs \"AND\" to describe it, split it\n\nExamples:\n```\n\u2705 GOOD: user-auth, user-sessions, payment-capture, payment-refunds\n\u274C BAD: users, payments, core, misc\n```\n\n## Key Behavioral Rules\n\n### 1. Always Start by Reading\n\nBefore any task:\n1. **Read relevant specs** in `specs/[capability]/spec.md` to understand current state\n2. **Check pending changes** in `changes/` directory for potential conflicts\n3. **Read project.md** for project-specific conventions\n\n### 2. When to Create Change Proposals\n\n**ALWAYS create a change proposal for:**\n- New features or functionality\n- Breaking changes (API changes, schema updates)\n- Architecture changes or new patterns\n- Performance optimizations that change behavior\n- Security updates affecting auth/access patterns\n- Any change requiring multiple steps or affecting multiple systems\n\n**SKIP proposals for:**\n- Bug fixes that restore intended behavior\n- Typos, formatting, or comment updates\n- Dependency updates (unless breaking)\n- Configuration or environment variable changes\n- Adding tests for existing behavior\n- Documentation fixes\n\n**Complexity assessment:**\n- If your solution requires >100 lines of new code, justify the complexity\n- If adding dependencies, frameworks, or architectural patterns, document why simpler alternatives won't work\n- Default to single-file implementations until proven insufficient\n\n### 3. Delta-Based Change Format\n\nChanges use a delta format with clear sections:\n\n```markdown\n## ADDED Requirements\n### Requirement: New Feature\n[Complete requirement content in structured format]\n\n## MODIFIED Requirements  \n### Requirement: Existing Feature\n[Complete modified requirement (header must match current spec)]\n\n## REMOVED Requirements\n### Requirement: Old Feature\n**Reason for removal**: [Why removing]\n**Migration path**: [How to handle existing usage]\n\n## RENAMED Requirements\n- FROM: `### Requirement: Old Name`\n- TO: `### Requirement: New Name`\n```\n\nKey rules:\n- Headers are matched using `normalize(header) = trim(header)`\n- Include complete requirements (not diffs)\n- Use standard symbols in CLI output: + (added), ~ (modified), - (removed), \u2192 (renamed)\n\n### 4. Creating a Change Proposal\n\nWhen a user requests a significant change:\n\n```bash\n# 1. Create the change directory\nopenspec/changes/[descriptive-name]/\n\n# 2. Generate proposal.md with all context\n## Why\n[1-2 sentences on the problem/opportunity]\n\n## What Changes  \n[Bullet list of changes, including breaking changes]\n\n## Impact\n- Affected specs: [list capabilities that will change]\n- Affected code: [list key files/systems]\n\n# 3. Create delta specs for ALL affected capabilities\n# - Store only the changes (not complete future state)\n# - Use sections: ## ADDED, ## MODIFIED, ## REMOVED, ## RENAMED\n# - Include complete requirements in their final form\n# Example spec.md content:\n#   ## ADDED Requirements\n#   ### Requirement: Password Reset\n#   Users SHALL be able to reset passwords via email...\n#   \n#   ## MODIFIED Requirements\n#   ### Requirement: User Authentication\n#   [Complete modified requirement with new password reset hook]\nspecs/\n\u2514\u2500\u2500 [capability]/\n    \u2514\u2500\u2500 spec.md  # Contains delta sections\n\n# 4. Create tasks.md with implementation steps\n## 1. [Task Group]\n- [ ] 1.1 [Specific task]\n- [ ] 1.2 [Specific task]\n\n# 5. For complex changes, add design.md\n[Technical decisions and trade-offs]\n```\n\n### 5. The Change Lifecycle\n\n1. **Propose** \u2192 Create change directory with delta-based documentation\n2. **Review** \u2192 User reviews and approves the proposal\n3. **Implement** \u2192 Follow the approved tasks.md (can be multiple PRs)\n4. **Deploy** \u2192 User confirms deployment\n5. **Update Specs** \u2192 Apply deltas to sync specs/ with new reality (IF the change affects system capabilities)\n6. **Archive** \u2192 Move to `changes/archive/YYYY-MM-DD-[name]/`\n\n### 6. Implementing Changes\n\nWhen implementing an approved change:\n1. Follow the tasks.md checklist exactly\n2. **Mark completed tasks** in tasks.md as you finish them (e.g., `- [x] 1.1 Task completed`)\n3. Ensure code matches the proposed behavior\n4. Update any affected tests\n5. **Keep change in `changes/` directory** - do NOT archive in implementation PR\n\n**Multiple Implementation PRs:**\n- Changes can be implemented across multiple PRs\n- Each PR should update tasks.md to mark what was completed\n- Different developers can work on different task groups\n- Example: PR #1 completes tasks 1.1-1.3, PR #2 completes tasks 2.1-2.4\n\n### 7. Updating Specs and Archiving After Deployment\n\n**Create a separate PR after deployment** that:\n1. Moves change to `changes/archive/YYYY-MM-DD-[name]/`\n2. Updates relevant files in `specs/` to reflect new reality (if needed)\n3. If design.md exists, incorporates proven patterns into `specs/[capability]/design.md`\n\nThis ensures changes are only archived when truly complete and deployed.\n\n### 8. Types of Changes That Don't Require Specs\n\nSome changes only affect development infrastructure and don't need specs:\n- Initial project setup (package.json, tsconfig.json, etc.)\n- Development tooling changes (linters, formatters, build tools)\n- CI/CD configuration\n- Development dependencies\n\nFor these changes:\n1. Implement \u2192 Deploy \u2192 Mark tasks complete \u2192 Archive\n2. Skip the \"Update Specs\" step entirely\n\n### What Deserves a Spec?\n\nAsk yourself:\n- Is this a system capability that users or other systems interact with?\n- Does it have ongoing behavior that needs documentation?\n- Would a new developer need to understand this to work with the system?\n\nIf NO to all \u2192 No spec needed (likely just tooling/infrastructure)\n\n## Understanding Specs vs Code\n\n### Specs Document WHAT and WHY\n```markdown\n# Authentication Spec\n\nUsers SHALL authenticate with email and password.\n\nWHEN credentials are valid THEN issue JWT token.\nWHEN credentials are invalid THEN return generic error.\n\nWHY: Prevent user enumeration attacks.\n```\n\n### Code Documents HOW\n```javascript\n// Implementation details\nconst user = await db.users.findOne({ email });\nconst valid = await bcrypt.compare(password, user.hashedPassword);\n```\n\n**Key Distinction**: Specs capture intent, constraints, and decisions that aren't obvious from code.\n\n## Common Scenarios\n\n### New Feature Request\n```\nUser: \"Add password reset functionality\"\n\nYou should:\n1. Read specs/user-auth/spec.md\n2. Check changes/ for pending auth changes\n3. Create changes/add-password-reset/ with:\n   - proposal.md describing the change\n   - specs/user-auth/spec.md with:\n     ## ADDED Requirements\n     ### Requirement: Password Reset\n     [Complete requirement for password reset]\n     \n     ## MODIFIED Requirements\n     ### Requirement: User Authentication\n     [Updated to integrate with password reset]\n4. Wait for approval before implementing\n```\n\n### Bug Fix\n```\nUser: \"Getting null pointer error when bio is empty\"\n\nYou should:\n1. Check if spec says bios are optional\n2. If yes \u2192 Fix directly (it's a bug)\n3. If no \u2192 Create change proposal (it's a behavior change)\n```\n\n### Infrastructure Setup\n```\nUser: \"Initialize TypeScript project\"\n\nYou should:\n1. Create change proposal for TypeScript setup\n2. Implement configuration files (PR #1)\n3. Mark tasks complete in tasks.md\n4. After deployment, create separate PR to archive\n   (no specs update needed - this is tooling, not a capability)\n```\n\n## Summary Workflow\n\n1. **Receive request** \u2192 Determine if it needs a change proposal\n2. **Read current state** \u2192 Check specs and pending changes\n3. **Create proposal** \u2192 Generate complete change documentation\n4. **Get approval** \u2192 User reviews the proposal\n5. **Implement** \u2192 Follow approved tasks, mark completed items in tasks.md\n6. **Deploy** \u2192 User deploys the implementation\n7. **Archive PR** \u2192 Create separate PR to:\n   - Move change to archive\n   - Update specs if needed\n   - Mark change as complete\n\n## PR Workflow Examples\n\n### Single Developer, Simple Change\n```\nPR #1: Implementation\n- Implement all tasks\n- Update tasks.md marking items complete\n- Get merged and deployed\n\nPR #2: Archive (after deployment)\n- Move changes/feature-x/ \u2192 changes/archive/2025-01-15-feature-x/\n- Update specs if needed\n```\n\n### Multiple Developers, Complex Change\n```\nPR #1: Alice implements auth components\n- Complete tasks 1.1, 1.2, 1.3\n- Update tasks.md marking these complete\n\nPR #2: Bob implements UI components  \n- Complete tasks 2.1, 2.2\n- Update tasks.md marking these complete\n\nPR #3: Alice fixes integration issues\n- Complete remaining task 1.4\n- Update tasks.md\n\n[Deploy all changes]\n\nPR #4: Archive\n- Move to archive with deployment date\n- Update specs to reflect new auth flow\n```\n\n### Key Rules\n- **Never archive in implementation PRs** - changes aren't done until deployed\n- **Always update tasks.md** - shows accurate progress\n- **One archive PR per change** - clear completion boundary\n- **Archive PR includes spec updates** - keeps specs current\n\n## Capability Organization Best Practices\n\n### Naming Capabilities\n- Use **verb-noun** patterns: `user-auth`, `payment-capture`, `order-checkout`\n- Be specific: `payment-capture` not just `payments`\n- Keep flat: Avoid nesting capabilities within capabilities\n- Singular focus: If you need \"AND\" to describe it, split it\n\n### When to Split Capabilities\nSplit when you have:\n- Multiple unrelated API endpoints\n- Different user personas or actors\n- Separate deployment considerations\n- Independent evolution paths\n\n#### Capability Boundary Guidelines\n- Would you import these separately? \u2192 Separate capabilities\n- Different deployment cadence? \u2192 Separate capabilities\n- Different teams own them? \u2192 Separate capabilities\n- Shared data models are OK, shared business logic means combine\n\nExamples:\n- user-auth (login/logout) vs user-sessions (token management) \u2192 SEPARATE\n- payment-capture vs payment-refunds \u2192 SEPARATE (different workflows)\n- user-profile vs user-settings \u2192 COMBINE (same data model, same owner)\n\n### Cross-Cutting Concerns\nFor system-wide policies (rate limiting, error handling, security), document them in:\n- `project.md` for project-wide conventions\n- Within relevant capability specs where they apply\n- Or create a dedicated capability if complex enough (e.g., `api-rate-limiting/`)\n\n### Examples of Well-Organized Capabilities\n```\nspecs/\n\u251C\u2500\u2500 user-auth/              # Login, logout, password reset\n\u251C\u2500\u2500 user-sessions/          # Token management, refresh\n\u251C\u2500\u2500 user-profile/           # Profile CRUD operations\n\u251C\u2500\u2500 payment-capture/        # Processing payments\n\u251C\u2500\u2500 payment-refunds/        # Handling refunds\n\u2514\u2500\u2500 order-checkout/         # Checkout workflow\n```\n\nFor detailed guidance, see the [Capability Organization Guide](../docs/capability-organization.md).\n\n## Common Scenarios and Clarifications\n\n### Decision Ambiguity: Bug vs Behavior Change\n\nWhen specs are missing or ambiguous:\n- If NO spec exists \u2192 Treat current code behavior as implicit spec, require proposal\n- If spec is VAGUE \u2192 Require proposal to clarify spec alongside fix\n- If code and spec DISAGREE \u2192 Spec is truth, code is buggy (fix without proposal)\n- If unsure \u2192 Default to creating a proposal (safer option)\n\nExample:\n```\nUser: \"The API returns 404 for missing users but should return 400\"\nAI: Is this a bug (spec says 400) or behavior change (spec says 404)?\n```\n\n### When You Don't Know the Scope\nIt's OK to explore first! Tell the user you need to investigate, then create an informed proposal.\n\n### Exploration Phase (When Needed)\n\nBEFORE creating proposal, you may need exploration when:\n- User request is vague or high-level\n- Multiple implementation approaches exist\n- Scope is unclear without seeing code\n\nExploration checklist:\n1. Tell user you need to explore first\n2. Use Grep/Read to understand current state\n3. Create initial proposal based on findings\n4. Refine with user feedback\n\nExample:\n```\nUser: \"Add caching to improve performance\"\nAI: \"Let me explore the codebase to understand the current architecture and identify caching opportunities.\"\n[After exploration]\nAI: \"Based on my analysis, I've identified three areas where caching would help. Here's my proposal...\"\n```\n\n### When No Specs Exist\nTreat current code as implicit spec. Your proposal should document current state AND proposed changes.\n\n### When in Doubt\nDefault to creating a proposal. It's easier to skip an unnecessary proposal than fix an undocumented change.\n\n### AI Workflow Adaptations\n\nTask tracking with OpenSpec:\n- Track exploration tasks separately from implementation\n- Document proposal creation steps as you go\n- Keep implementation tasks separate until proposal approved\n\nParallel operations encouraged:\n- Read multiple specs simultaneously\n- Check multiple pending changes at once\n- Batch related searches for efficiency\n\nProgress communication:\n- \"Exploring codebase to understand scope...\"\n- \"Creating proposal based on findings...\"\n- \"Implementing approved changes...\"\n\n### For AI Assistants\n- **Bias toward simplicity** - Propose the minimal solution that works\n- Use your exploration tools liberally before proposing\n- Batch operations for efficiency\n- Communicate your progress\n- It's OK to revise proposals based on discoveries\n- **Question complexity** - If your solution feels complex, simplify first\n\n## Edge Case Handling\n\n### Multi-Capability Changes\nCreate ONE proposal that:\n- Lists all affected capabilities\n- Shows changes per capability\n- Has unified task list\n- Gets approved as a whole\n\n### Outdated Specs\nIf specs clearly outdated:\n1. Create proposal to update specs to match reality\n2. Implement new feature in separate proposal\n3. OR combine both in one proposal with clear sections\n\n### Emergency Hotfixes\nFor critical production issues:\n1. Announce: \"This is an emergency fix\"\n2. Implement fix immediately\n3. Create retroactive proposal\n4. Update specs after deployment\n5. Tag with [EMERGENCY] in archive\n\n### Pure Refactoring\nNo proposal needed for:\n- Code formatting/style\n- Internal refactoring (same API)\n- Performance optimization (same behavior)\n- Adding types to untyped code\n\nProposal REQUIRED for:\n- API changes (even if compatible)\n- Database schema changes\n- Architecture changes\n- New dependencies\n\n### Observability Additions\nNo proposal needed for:\n- Adding log statements\n- New metrics/traces\n- Debugging additions\n- Error tracking\n\nProposal REQUIRED if:\n- Changes log format/structure\n- Adds new monitoring service\n- Changes what's logged (privacy)\n\n## Remember\n\n- You are the process driver - automate documentation burden\n- Specs must always reflect deployed reality\n- Changes are proposed, not imposed\n- Impact analysis prevents surprises\n- Simplicity is the power - just markdown files, minimal solutions\n- Start simple, add complexity only when justified\n\nBy following these conventions, you enable true spec-driven development where documentation stays current, changes are traceable, and evolution is intentional.\n";
+//# sourceMappingURL=readme-template.d.ts.map