@dedesfr/prompter 0.9.0 → 1.0.0

package/src/core/templates/agents-template.ts

@@ -1,459 +0,0 @@
-export const agentsTemplate = `# Prompter Instructions
-
-Instructions for AI coding assistants using Prompter for spec-driven development.
-
-## TL;DR Quick Checklist
-
-- Search existing work: \`prompter spec list --long\`, \`prompter list\` (use \`rg\` only for full-text search)
-- Decide scope: new capability vs modify existing capability
-- Pick a unique \`change-id\`: kebab-case, verb-led (\`add-\`, \`update-\`, \`remove-\`, \`refactor-\`)
-- Scaffold: \`proposal.md\`, \`tasks.md\`, \`design.md\` (only if needed), and delta specs per affected capability
-- Write deltas: use \`## ADDED|MODIFIED|REMOVED|RENAMED Requirements\`; include at least one \`#### Scenario:\` per requirement
-- Validate: \`prompter validate [change-id] --strict --no-interactive\` and fix issues
-- Request approval: Do not start implementation until proposal is approved
-
-## Three-Stage Workflow
-
-### Stage 1: Creating Changes
-Create proposal when you need to:
-- Add features or functionality
-- Make breaking changes (API, schema)
-- Change architecture or patterns  
-- Optimize performance (changes behavior)
-- Update security patterns
-
-Triggers (examples):
-- "Help me create a change proposal"
-- "Help me plan a change"
-- "Help me create a proposal"
-- "I want to create a spec proposal"
-- "I want to create a spec"
-
-Loose matching guidance:
-- Contains one of: \`proposal\`, \`change\`, \`spec\`
-- With one of: \`create\`, \`plan\`, \`make\`, \`start\`, \`help\`
-
-Skip proposal for:
-- Bug fixes (restore intended behavior)
-- Typos, formatting, comments
-- Dependency updates (non-breaking)
-- Configuration changes
-- Tests for existing behavior
-
-**Workflow**
-1. Review \`prompter/project.md\`, \`prompter list\`, and \`prompter list --specs\` to understand current context.
-2. Choose a unique verb-led \`change-id\` and scaffold \`proposal.md\`, \`tasks.md\`, optional \`design.md\`, and spec deltas under \`prompter/changes/<id>/\`.
-3. Draft spec deltas using \`## ADDED|MODIFIED|REMOVED Requirements\` with at least one \`#### Scenario:\` per requirement.
-4. Run \`prompter validate <id> --strict --no-interactive\` and resolve any issues before sharing the proposal.
-
-### Stage 2: Implementing Changes
-Track these steps as TODOs and complete them one by one.
-1. **Read proposal.md** - Understand what's being built
-2. **Read design.md** (if exists) - Review technical decisions
-3. **Read tasks.md** - Get implementation checklist
-4. **Implement tasks sequentially** - Complete in order
-5. **Confirm completion** - Ensure every item in \`tasks.md\` is finished before updating statuses
-6. **Update checklist** - After all work is done, set every task to \`- [x]\` so the list reflects reality
-7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
-
-### Stage 3: Archiving Changes
-After deployment, create separate PR to:
-- Move \`changes/[name]/\` → \`changes/archive/YYYY-MM-DD-[name]/\`
-- Update \`specs/\` if capabilities changed
-- Use \`prompter archive <change-id> --skip-specs --yes\` for tooling-only changes (always pass the change ID explicitly)
-- Run \`prompter validate --strict --no-interactive\` to confirm the archived change passes checks
-
-## Before Any Task
-
-**Context Checklist:**
-- [ ] Read relevant specs in \`specs/[capability]/spec.md\`
-- [ ] Check pending changes in \`changes/\` for conflicts
-- [ ] Read \`prompter/project.md\` for conventions
-- [ ] Run \`prompter list\` to see active changes
-- [ ] Run \`prompter list --specs\` to see existing capabilities
-
-**Before Creating Specs:**
-- Always check if capability already exists
-- Prefer modifying existing specs over creating duplicates
-- Use \`prompter show [spec]\` to review current state
-- If request is ambiguous, ask 1–2 clarifying questions before scaffolding
-
-### Search Guidance
-- Enumerate specs: \`prompter spec list --long\` (or \`--json\` for scripts)
-- Enumerate changes: \`prompter list\` (or \`prompter change list --json\` - deprecated but available)
-- Show details:
-  - Spec: \`prompter show <spec-id> --type spec\` (use \`--json\` for filters)
-  - Change: \`prompter show <change-id> --json --deltas-only\`
-- Full-text search (use ripgrep): \`rg -n "Requirement:|Scenario:" prompter/specs\`
-
-## Quick Start
-
-### CLI Commands
-
-\`\`\`bash
-# Essential commands
-prompter list                  # List active changes
-prompter list --specs          # List specifications
-prompter show [item]           # Display change or spec
-prompter validate [item]       # Validate changes or specs
-prompter archive <change-id> [--yes|-y]   # Archive after deployment (add --yes for non-interactive runs)
-
-# Project management
-prompter init [path]           # Initialize Prompter
-
-# Interactive mode
-prompter show                  # Prompts for selection
-prompter validate              # Bulk validation mode
-
-# Debugging
-prompter show [change] --json --deltas-only
-prompter validate [change] --strict --no-interactive
-\`\`\`
-
-### Command Flags
-
-- \`--json\` - Machine-readable output
-- \`--type change|spec\` - Disambiguate items
-- \`--strict\` - Comprehensive validation
-- \`--no-interactive\` - Disable prompts
-- \`--skip-specs\` - Archive without spec updates
-- \`--yes\`/\`-y\` - Skip confirmation prompts (non-interactive archive)
-
-## Directory Structure
-
-\`\`\`
-prompter/
-├── project.md              # Project conventions
-├── specs/                  # Current truth - what IS built
-│   └── [capability]/       # Single focused capability
-│       ├── spec.md         # Requirements and scenarios
-│       └── design.md       # Technical patterns
-├── changes/                # Proposals - what SHOULD change
-│   ├── [change-name]/
-│   │   ├── proposal.md     # Why, what, impact
-│   │   ├── tasks.md        # Implementation checklist
-│   │   ├── design.md       # Technical decisions (optional; see criteria)
-│   │   └── specs/          # Delta changes
-│   │       └── [capability]/
-│   │           └── spec.md # ADDED/MODIFIED/REMOVED
-│   └── archive/            # Completed changes
-\`\`\`
-
-## Creating Change Proposals
-
-### Decision Tree
-
-\`\`\`
-New request?
-├─ Bug fix restoring spec behavior? → Fix directly
-├─ Typo/format/comment? → Fix directly  
-├─ New feature/capability? → Create proposal
-├─ Breaking change? → Create proposal
-├─ Architecture change? → Create proposal
-└─ Unclear? → Create proposal (safer)
-\`\`\`
-
-### Proposal Structure
-
-1. **Create directory:** \`changes/[change-id]/\` (kebab-case, verb-led, unique)
-
-2. **Write proposal.md:**
-\`\`\`markdown
-# Change: [Brief description of change]
-
-## Why
-[1-2 sentences on problem/opportunity]
-
-## What Changes
-- [Bullet list of changes]
-- [Mark breaking changes with **BREAKING**]
-
-## Impact
-- Affected specs: [list capabilities]
-- Affected code: [key files/systems]
-\`\`\`
-
-3. **Create spec deltas:** \`specs/[capability]/spec.md\`
-\`\`\`markdown
-## ADDED Requirements
-### Requirement: New Feature
-The system SHALL provide...
-
-#### Scenario: Success case
-- **WHEN** user performs action
-- **THEN** expected result
-
-## MODIFIED Requirements
-### Requirement: Existing Feature
-[Complete modified requirement]
-
-## REMOVED Requirements
-### Requirement: Old Feature
-**Reason**: [Why removing]
-**Migration**: [How to handle]
-\`\`\`
-If multiple capabilities are affected, create multiple delta files under \`changes/[change-id]/specs/<capability>/spec.md\`—one per capability.
-
-4. **Create tasks.md:**
-\`\`\`markdown
-## 1. Implementation
-- [ ] 1.1 Create database schema
-- [ ] 1.2 Implement API endpoint
-- [ ] 1.3 Add frontend component
-- [ ] 1.4 Write tests
-
-## Post-Implementation
-- [ ] Update AGENTS.md in the project root for new changes in this specs
-\`\`\`
-
-5. **Create design.md when needed:**
-Create \`design.md\` if any of the following apply; otherwise omit it:
-- Cross-cutting change (multiple services/modules) or a new architectural pattern
-- New external dependency or significant data model changes
-- Security, performance, or migration complexity
-- Ambiguity that benefits from technical decisions before coding
-
-Minimal \`design.md\` skeleton:
-\`\`\`markdown
-## Context
-[Background, constraints, stakeholders]
-
-## Goals / Non-Goals
-- Goals: [...]
-- Non-Goals: [...]
-
-## Decisions
-- Decision: [What and why]
-- Alternatives considered: [Options + rationale]
-
-## Risks / Trade-offs
-- [Risk] → Mitigation
-
-## Migration Plan
-[Steps, rollback]
-
-## Open Questions
-- [...]
-\`\`\`
-
-## Spec File Format
-
-### Critical: Scenario Formatting
-
-**CORRECT** (use #### headers):
-\`\`\`markdown
-#### Scenario: User login success
-- **WHEN** valid credentials provided
-- **THEN** return JWT token
-\`\`\`
-
-**WRONG** (don't use bullets or bold):
-\`\`\`markdown
-- **Scenario: User login**  ❌
-**Scenario**: User login     ❌
-### Scenario: User login      ❌
-\`\`\`
-
-Every requirement MUST have at least one scenario.
-
-### Requirement Wording
-- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
-
-### Delta Operations
-
-- \`## ADDED Requirements\` - New capabilities
-- \`## MODIFIED Requirements\` - Changed behavior
-- \`## REMOVED Requirements\` - Deprecated features
-- \`## RENAMED Requirements\` - Name changes
-
-Headers matched with \`trim(header)\` - whitespace ignored.
-
-#### When to use ADDED vs MODIFIED
-- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
-- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
-- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
-
-Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
-
-Authoring a MODIFIED requirement correctly:
-1) Locate the existing requirement in \`prompter/specs/<capability>/spec.md\`.
-2) Copy the entire requirement block (from \`### Requirement: ...\` through its scenarios).
-3) Paste it under \`## MODIFIED Requirements\` and edit to reflect the new behavior.
-4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one \`#### Scenario:\`.
-
-Example for RENAMED:
-\`\`\`markdown
-## RENAMED Requirements
-- FROM: \`### Requirement: Login\`
-- TO: \`### Requirement: User Authentication\`
-\`\`\`
-
-## Troubleshooting
-
-### Common Errors
-
-**"Change must have at least one delta"**
-- Check \`changes/[name]/specs/\` exists with .md files
-- Verify files have operation prefixes (## ADDED Requirements)
-
-**"Requirement must have at least one scenario"**
-- Check scenarios use \`#### Scenario:\` format (4 hashtags)
-- Don't use bullet points or bold for scenario headers
-
-**Silent scenario parsing failures**
-- Exact format required: \`#### Scenario: Name\`
-- Debug with: \`prompter show [change] --json --deltas-only\`
-
-### Validation Tips
-
-\`\`\`bash
-# Always use strict mode for comprehensive checks
-prompter validate [change] --strict --no-interactive
-
-# Debug delta parsing
-prompter show [change] --json | jq '.deltas'
-
-# Check specific requirement
-prompter show [spec] --json -r 1
-\`\`\`
-
-## Happy Path Script
-
-\`\`\`bash
-# 1) Explore current state
-prompter spec list --long
-prompter list
-# Optional full-text search:
-# rg -n "Requirement:|Scenario:" prompter/specs
-# rg -n "^#|Requirement:" prompter/changes
-
-# 2) Choose change id and scaffold
-CHANGE=add-two-factor-auth
-mkdir -p prompter/changes/$CHANGE/{specs/auth}
-printf "## Why\\n...\\n\\n## What Changes\\n- ...\\n\\n## Impact\\n- ...\\n" > prompter/changes/$CHANGE/proposal.md
-printf "## 1. Implementation\\n- [ ] 1.1 ...\\n" > prompter/changes/$CHANGE/tasks.md
-
-# 3) Add deltas (example)
-cat > prompter/changes/$CHANGE/specs/auth/spec.md << 'EOF'
-## ADDED Requirements
-### Requirement: Two-Factor Authentication
-Users MUST provide a second factor during login.
-
-#### Scenario: OTP required
-- **WHEN** valid credentials are provided
-- **THEN** an OTP challenge is required
-EOF
-
-# 4) Validate
-prompter validate $CHANGE --strict --no-interactive
-\`\`\`
-
-## Multi-Capability Example
-
-\`\`\`
-prompter/changes/add-2fa-notify/
-├── proposal.md
-├── tasks.md
-└── specs/
-    ├── auth/
-    │   └── spec.md   # ADDED: Two-Factor Authentication
-    └── notifications/
-        └── spec.md   # ADDED: OTP email notification
-\`\`\`
-
-auth/spec.md
-\`\`\`markdown
-## ADDED Requirements
-### Requirement: Two-Factor Authentication
-...
-\`\`\`
-
-notifications/spec.md
-\`\`\`markdown
-## ADDED Requirements
-### Requirement: OTP Email Notification
-...
-\`\`\`
-
-## Best Practices
-
-### Simplicity First
-- Default to <100 lines of new code
-- Single-file implementations until proven insufficient
-- Avoid frameworks without clear justification
-- Choose boring, proven patterns
-
-### Complexity Triggers
-Only add complexity with:
-- Performance data showing current solution too slow
-- Concrete scale requirements (>1000 users, >100MB data)
-- Multiple proven use cases requiring abstraction
-
-### Clear References
-- Use \`file.ts:42\` format for code locations
-- Reference specs as \`specs/auth/spec.md\`
-- Link related changes and PRs
-
-### Capability Naming
-- Use verb-noun: \`user-auth\`, \`payment-capture\`
-- Single purpose per capability
-- 10-minute understandability rule
-- Split if description needs "AND"
-
-### Change ID Naming
-- Use kebab-case, short and descriptive: \`add-two-factor-auth\`
-- Prefer verb-led prefixes: \`add-\`, \`update-\`, \`remove-\`, \`refactor-\`
-- Ensure uniqueness; if taken, append \`-2\`, \`-3\`, etc.
-
-## Tool Selection Guide
-
-| Task | Tool | Why |
-|------|------|-----|
-| Find files by pattern | Glob | Fast pattern matching |
-| Search code content | Grep | Optimized regex search |
-| Read specific files | Read | Direct file access |
-| Explore unknown scope | Task | Multi-step investigation |
-
-## Error Recovery
-
-### Change Conflicts
-1. Run \`prompter list\` to see active changes
-2. Check for overlapping specs
-3. Coordinate with change owners
-4. Consider combining proposals
-
-### Validation Failures
-1. Run with \`--strict\` flag
-2. Check JSON output for details
-3. Verify spec file format
-4. Ensure scenarios properly formatted
-
-### Missing Context
-1. Read project.md first
-2. Check related specs
-3. Review recent archives
-4. Ask for clarification
-
-## Quick Reference
-
-### Stage Indicators
-- \`changes/\` - Proposed, not yet built
-- \`specs/\` - Built and deployed
-- \`archive/\` - Completed changes
-
-### File Purposes
-- \`proposal.md\` - Why and what
-- \`tasks.md\` - Implementation steps
-- \`design.md\` - Technical decisions
-- \`spec.md\` - Requirements and behavior
-
-### CLI Essentials
-\`\`\`bash
-prompter list              # What's in progress?
-prompter show [item]       # View details
-prompter validate --strict --no-interactive  # Is it correct?
-prompter archive <change-id> [--yes|-y]  # Mark complete (add --yes for automation)
-\`\`\`
-
-Remember: Specs are truth. Changes are proposals. Keep them in sync.
-`;

package/src/core/templates/claude-template.ts

@@ -1,2 +0,0 @@
-// Claude Code uses CLAUDE.md - same content as AGENTS.md
-export { agentsTemplate as claudeTemplate } from './agents-template.js';

package/src/core/templates/index.ts

@@ -1,3 +0,0 @@
-export { projectTemplate } from './project-template.js';
-export { agentsTemplate } from './agents-template.js';
-export { claudeTemplate } from './claude-template.js';

package/src/core/templates/project-template.ts

@@ -1,32 +0,0 @@
-export const projectTemplate = `# Project Context
-
-## Purpose
-[Describe your project's purpose and goals]
-
-## Tech Stack
-- [List your primary technologies]
-- [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]
-`;

package/src/core/validation/constants.ts

@@ -1,48 +0,0 @@
-/**
- * Validation threshold constants
- */
-
-// Minimum character lengths
-export const MIN_WHY_SECTION_LENGTH = 50;
-export const MIN_PURPOSE_LENGTH = 50;
-
-// Maximum character/item limits
-export const MAX_WHY_SECTION_LENGTH = 1000;
-export const MAX_REQUIREMENT_TEXT_LENGTH = 500;
-export const MAX_DELTAS_PER_CHANGE = 10;
-
-// Validation messages
-export const VALIDATION_MESSAGES = {
-  // Required content
-  SCENARIO_EMPTY: 'Scenario text cannot be empty',
-  REQUIREMENT_EMPTY: 'Requirement text cannot be empty',
-  REQUIREMENT_NO_SHALL: 'Requirement must contain SHALL or MUST keyword',
-  REQUIREMENT_NO_SCENARIOS: 'Requirement must have at least one scenario',
-  SPEC_NAME_EMPTY: 'Spec name cannot be empty',
-  SPEC_PURPOSE_EMPTY: 'Purpose section cannot be empty',
-  SPEC_NO_REQUIREMENTS: 'Spec must have at least one requirement',
-  CHANGE_NAME_EMPTY: 'Change name cannot be empty',
-  CHANGE_WHY_TOO_SHORT: `Why section must be at least ${MIN_WHY_SECTION_LENGTH} characters`,
-  CHANGE_WHY_TOO_LONG: `Why section should not exceed ${MAX_WHY_SECTION_LENGTH} characters`,
-  CHANGE_WHAT_EMPTY: 'What Changes section cannot be empty',
-  CHANGE_NO_DELTAS: 'Change must have at least one delta',
-  CHANGE_TOO_MANY_DELTAS: `Consider splitting changes with more than ${MAX_DELTAS_PER_CHANGE} deltas`,
-  DELTA_SPEC_EMPTY: 'Spec name cannot be empty',
-  DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
-  
-  // Warnings
-  PURPOSE_TOO_BRIEF: `Purpose section is too brief (less than ${MIN_PURPOSE_LENGTH} characters)`,
-  REQUIREMENT_TOO_LONG: `Requirement text is very long (>${MAX_REQUIREMENT_TEXT_LENGTH} characters). Consider breaking it down.`,
-  DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
-  DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
-  
-  // Guidance snippets (appended to primary messages for remediation)
-  GUIDE_NO_DELTAS:
-    'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "prompter change show <change-id> --json --deltas-only" to inspect parsed deltas.',
-  GUIDE_MISSING_SPEC_SECTIONS:
-    'Missing required sections. Expected headers: "## Purpose" and "## Requirements". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...',
-  GUIDE_MISSING_CHANGE_SECTIONS:
-    'Missing required sections. Expected headers: "## Why" and "## What Changes". Ensure deltas are documented in specs/ using delta headers.',
-  GUIDE_SCENARIO_FORMAT:
-    'Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...',
-} as const;

package/src/core/validation/types.ts

@@ -1,19 +0,0 @@
-export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
-
-export interface ValidationIssue {
-  level: ValidationLevel;
-  path: string;
-  message: string;
-  line?: number;
-  column?: number;
-}
-
-export interface ValidationReport {
-  valid: boolean;
-  issues: ValidationIssue[];
-  summary: {
-    errors: number;
-    warnings: number;
-    info: number;
-  };
-}