@compilr-dev/agents 0.1.0 → 0.2.1

package/dist/skills/index.js

@@ -261,6 +261,697 @@ Provide actionable plans with clear next steps.`,
 Apply OWASP guidelines and security best practices.`,
         tags: ['security', 'review'],
     }),
+    defineSkill({
+        name: 'design',
+        description: 'Guide user through project design and requirements gathering',
+        prompt: `You are in DESIGN MODE. Your goal is to gather enough information to populate the project backlog with 5-15 actionable items.
+
+## PHASES
+
+### Phase 1: Vision (3-5 questions)
+Understand the big picture:
+- What problem does this solve?
+- Who is the target user/customer?
+- What's the one-sentence pitch?
+- What makes this different from alternatives?
+
+After gathering answers, summarize the vision and confirm with user.
+
+### Phase 2: Core Features (3-5 questions)
+Define MVP scope:
+- What are the 3-5 must-have features for v1?
+- What explicitly can wait for v2?
+- Are there any non-negotiable technical requirements?
+
+Use the ask_user tool to present feature options when helpful.
+
+### Phase 3: Technical Context (2-3 questions)
+Understand constraints:
+- Any existing systems to integrate with?
+- Performance/scale requirements?
+- Compliance/security requirements?
+
+### Phase 4: Output
+When you have enough information:
+1. Summarize the design in a concise format
+2. Check if project needs foundation:
+   - Use detect_project tool to check current state
+   - If no src/, package.json, or code files exist → this is a fresh project
+3. Use backlog_write to create 5-15 items:
+   - **For fresh projects, ALWAYS add first:**
+     | CHORE-001 | chore | 📋 | critical | Project scaffolding | Create project structure, dependencies, and build config based on tech stack |
+   - Core features (type: feature, priority: high)
+   - Nice-to-haves (type: feature, priority: medium/low)
+   - Technical setup tasks (type: chore, priority: high)
+   - Known risks/unknowns (type: tech-debt, priority: medium)
+4. Update the PRD.md file with gathered requirements:
+   - Use the edit tool to update PRD.md (located in .compilr/requirements/PRD.md or {project}-docs/00-requirements/PRD.md)
+   - Fill in: Problem Statement, Goals, User Stories, Functional Requirements
+   - Keep the existing structure, just replace placeholder text
+5. Present the backlog and PRD summary to user for confirmation
+   - If CHORE-001 was added, mention: "Run /build to start with project scaffolding"
+
+## RULES
+- Ask questions in batches of 2-4 using ask_user tool when possible
+- Always offer a "Type something custom" option
+- Summarize after each phase before moving on
+- If user says "skip" or "later", move to next phase
+- Stop asking when you have enough for a meaningful backlog
+- Total interaction should be 10-20 questions max
+
+## COMPLETION CRITERIA
+✓ Vision is clear and confirmed
+✓ MVP features are defined
+✓ Backlog has 5-15 items
+✓ For fresh projects: CHORE-001 scaffolding item is first (critical priority)
+✓ PRD.md is populated with requirements
+✓ User has approved the backlog`,
+        tags: ['planning', 'requirements'],
+    }),
+    defineSkill({
+        name: 'refine',
+        description: 'Iteratively refine and expand project requirements',
+        prompt: `You are in REFINE MODE. Your goal is to deepen and expand existing requirements based on user feedback.
+
+## STARTUP
+
+1. Use todo_write to create a task list:
+   - "Get backlog overview"
+   - "Ask user what to refine"
+   - "Refine selected items"
+   - "Update backlog"
+
+2. Use backlog_read with limit:10 to get overview (NOT all items!)
+   - Note the total count and what types/priorities exist
+   - If total > 10, mention there are more items available
+
+3. Use ask_user_simple to ask what the user wants to focus on:
+   - Question: "What would you like to refine?"
+   - Options based on what you found (e.g., "High priority features", "Technical debt items", "A specific item by ID")
+
+## REFINEMENT APPROACHES
+
+### 1. Expand Existing Items
+For items that are too vague:
+- Break down into sub-tasks
+- Add acceptance criteria
+- Clarify scope boundaries
+
+### 2. Add Missing Items
+Identify gaps:
+- Edge cases not covered
+- Error handling scenarios
+- Integration points
+
+### 3. Reprioritize
+Based on new understanding:
+- Promote blockers, demote nice-to-haves
+- Identify dependencies
+
+### 4. Technical Deep-Dive
+For complex features:
+- Architecture decisions
+- Technology choices
+
+## TOOLS TO USE
+
+- **ask_user_simple**: For single-choice questions (preferred for most interactions)
+- **ask_user**: For multi-question batches (when gathering related info)
+- **backlog_read**: Use id param to get specific item, use search/filters otherwise
+- **backlog_write**: Update items after refinement decisions
+- **todo_write**: Track your progress through refinement
+
+## RULES
+
+1. ALWAYS use ask_user_simple or ask_user for decisions - NEVER ask questions in plain text
+2. Keep backlog reads efficient - use filters and limits
+3. One refinement focus at a time
+4. Update backlog with backlog_write after each decision
+5. Summarize changes at the end
+
+## COMPLETION CRITERIA
+✓ User's refinement goals are addressed
+✓ Backlog is updated with changes
+✓ No open questions remain`,
+        tags: ['planning', 'requirements'],
+    }),
+    defineSkill({
+        name: 'sketch',
+        description: 'Quick project outline with simple questions',
+        prompt: `You are in SKETCH MODE. Ask 6 quick questions, then create backlog items.
+
+STEPS:
+1. Use todo_write with 6 tasks (one per question)
+2. Ask each question using ask_user_simple tool
+3. After each answer, mark that todo complete
+4. After all questions, check if this is a fresh project:
+   - Use detect_project to check if src/, package.json, or code files exist
+   - If fresh project → add CHORE-001 scaffolding item first (critical priority)
+5. Use backlog_write to create 3-8 items
+6. Summarize and suggest /design for more detail (or /build to start scaffolding)
+
+QUESTIONS (ask one at a time):
+1. App type? Options: Web app, Mobile app, CLI tool, API service
+2. Target users? Options: Developers, Business users, Consumers, Internal team
+3. Main problem it solves? (free text, no options)
+4. Must-have features? (free text, no options)
+5. Tech needs? Options: Database, Authentication, External APIs, None
+6. Timeline? Options: Quick prototype, MVP in weeks, Full product
+
+RULES:
+- One ask_user_simple call per question
+- Keep it simple and fast
+- For fresh projects, ALWAYS add CHORE-001 scaffolding as first item`,
+        tags: ['planning', 'requirements'],
+    }),
+    defineSkill({
+        name: 'refine-item',
+        description: 'Focused refinement of a specific backlog item',
+        prompt: `You are in FOCUSED REFINE MODE. Your goal is to refine a specific backlog item.
+
+## STARTUP
+
+1. Use backlog_read with id parameter to get the specific item
+2. Use todo_write to track progress:
+   - "Review current item"
+   - "Gather refinement details"
+   - "Update backlog"
+
+3. Present the item and ask what to refine using ask_user_simple:
+   - Question: "How would you like to refine this item?"
+   - Options: "Break into subtasks", "Add details/criteria", "Change priority", "Technical deep-dive"
+
+## REFINEMENT FLOW
+
+Based on user's choice:
+
+### Break into subtasks
+- Use ask_user_simple to ask how many subtasks (2-5)
+- For each subtask, use ask_user_simple to get title
+- Use backlog_write to add new items
+- Optionally update original item status
+
+### Add details/criteria
+- Use ask_user to gather:
+  - Acceptance criteria
+  - Edge cases
+  - Dependencies
+- Use backlog_write to update description
+
+### Change priority
+- Use ask_user_simple with priority options
+- Use backlog_write to update
+
+### Technical deep-dive
+- Use ask_user to gather:
+  - Architecture approach
+  - Technology choices
+  - Risks/concerns
+- Add as new tech-debt item or update description
+
+## RULES
+
+1. ALWAYS use ask_user_simple for single choices
+2. Use ask_user for multi-field input
+3. Update backlog after each decision
+4. Summarize what was changed at the end
+
+## COMPLETION
+✓ Item is refined per user's request
+✓ Backlog is updated
+✓ Changes are summarized`,
+        tags: ['planning', 'requirements'],
+    }),
+    defineSkill({
+        name: 'architecture',
+        description: 'Create architecture documentation (ADRs, diagrams, data models, API designs)',
+        prompt: `You are in ARCHITECTURE MODE. Your goal is to create architecture documentation.
+
+## DOCUMENT TYPE: {{doc_type}}
+{{#if custom_topic}}Custom Topic: {{custom_topic}}{{/if}}
+
+## STARTUP
+
+1. Use todo_write to track your progress:
+   - "Read project context"
+   - "Gather requirements"
+   - "Create document"
+   - "Confirm with user"
+
+2. Read project context:
+   - Check for PRD.md (project vision and requirements)
+   - Use backlog_read with limit:10 for feature overview
+   - Check existing architecture docs to avoid duplicates
+
+## DOCUMENT TEMPLATES
+
+### For ADR (Architecture Decision Record)
+Location: .compilr/architecture/decisions/ADR-NNN-{{slug}}.md or {project}-docs/02-architecture/decisions/ADR-NNN-{{slug}}.md
+
+Use ask_user to gather:
+1. What decision is being documented?
+2. What problem or need prompted this decision?
+3. What alternatives were considered?
+4. What are the trade-offs of the chosen approach?
+
+Template:
+\`\`\`markdown
+# ADR-NNN: {{title}}
+
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Date:** {{YYYY-MM-DD}}
+**Deciders:** {{who made this decision}}
+
+---
+
+## Context
+
+{{What is the issue that we're seeing that is motivating this decision?}}
+
+## Decision
+
+{{What is the change that we're proposing and/or doing?}}
+
+## Consequences
+
+### Positive
+- {{benefit 1}}
+- {{benefit 2}}
+
+### Negative
+- {{trade-off 1}}
+- {{trade-off 2}}
+
+### Risks
+- {{risk 1}}
+
+---
+
+## Alternatives Considered
+
+### {{Alternative 1}}
+{{description}}
+**Rejected because:** {{reason}}
+
+---
+
+*Generated by /arch*
+\`\`\`
+
+### For System Diagram
+Location: .compilr/architecture/diagrams/{{slug}}.md or {project}-docs/02-architecture/diagrams/{{slug}}.md
+
+Use ask_user to gather:
+1. What are the main components/services?
+2. How do they communicate?
+3. What external integrations exist?
+4. What data flows between components?
+
+Generate a Mermaid diagram with explanation.
+
+### For Data Model
+Location: .compilr/architecture/data-model.md or {project}-docs/02-architecture/data-model.md
+
+Use ask_user to gather:
+1. What are the main entities?
+2. What are the relationships between them?
+3. What are the key fields and constraints?
+
+Generate entity descriptions and a Mermaid ER diagram.
+
+### For API Design
+Location: .compilr/architecture/api-design.md or {project}-docs/02-architecture/api-design.md
+
+Use ask_user to gather:
+1. What resources/endpoints are needed?
+2. What authentication approach?
+3. What are the main request/response formats?
+
+Generate OpenAPI-style documentation.
+
+### For Custom Topic
+Location: .compilr/architecture/{{slug}}.md or {project}-docs/02-architecture/{{slug}}.md
+
+Use ask_user to understand:
+1. What aspect of architecture to document?
+2. What level of detail is needed?
+3. Who is the audience?
+
+Generate appropriate documentation.
+
+## RULES
+
+1. Use ask_user or ask_user_simple for structured input
+2. Read existing docs first to avoid duplicates
+3. For ADRs, auto-number based on existing ADRs in the directory
+4. Create directories if they don't exist
+5. Follow the appropriate template for the document type
+6. Include Mermaid diagrams where helpful
+7. Summarize what was created at the end
+
+## COMPLETION CRITERIA
+✓ Document is created in correct location
+✓ All sections are properly filled in
+✓ Diagrams render correctly (valid Mermaid syntax)
+✓ User has reviewed the output`,
+        tags: ['architecture', 'documentation'],
+    }),
+    defineSkill({
+        name: 'prd',
+        description: 'Amend or enhance the Product Requirements Document',
+        prompt: `You are in PRD MODE. Your goal is to update or enhance the existing Product Requirements Document.
+
+## STARTUP
+
+1. Use todo_write to track your progress:
+   - "Read current PRD"
+   - "Identify section to update"
+   - "Gather updates"
+   - "Write updated PRD"
+
+2. Read the existing PRD.md:
+   - Location: .compilr/requirements/PRD.md or {project}-docs/00-requirements/PRD.md
+   - If no PRD exists, inform the user to run /design first
+
+3. Present current PRD sections to user using ask_user_simple:
+   - Question: "Which section would you like to update?"
+   - Options based on PRD structure (Vision, Scope, Technical, Success Criteria)
+
+## PRD STRUCTURE
+
+The PRD has these sections that can be updated:
+
+### 1. Vision
+- Problem Statement
+- Target Users
+- Value Proposition
+- Differentiation
+
+### 2. Scope
+- MVP Features (v1)
+- Future Features (v2+)
+- Out of Scope
+
+### 3. Technical Context
+- Integrations
+- Constraints (Performance, Scale, Compliance)
+- Tech Stack
+
+### 4. Success Criteria
+- How do we know when this is done?
+
+## UPDATE FLOW
+
+Based on section selected:
+
+1. Show current content of that section
+2. Use ask_user to gather:
+   - What to add/change
+   - What to remove
+   - Any clarifications
+3. Use the edit tool to update PRD.md
+4. Show the updated section for confirmation
+
+## RULES
+
+1. ALWAYS read the existing PRD first
+2. Use ask_user_simple for section selection
+3. Use ask_user for gathering detailed updates
+4. Preserve sections you're not updating
+5. Use edit tool (not write_file) to update specific sections
+6. Keep formatting consistent with existing document
+7. If scope changes affect backlog, suggest running /refine
+
+## COMPLETION CRITERIA
+✓ PRD.md is updated with changes
+✓ User has reviewed the updates
+✓ Related backlog updates are suggested if needed`,
+        tags: ['planning', 'requirements'],
+    }),
+    defineSkill({
+        name: 'session-notes',
+        description: 'Create structured session notes capturing work done and decisions made',
+        prompt: `You are in SESSION NOTES MODE. Your goal is to create a structured summary of the current session.
+
+## STARTUP
+
+1. Use todo_write to track your progress:
+   - "Gather session context"
+   - "Write session note"
+   - "Confirm with user"
+
+2. Review recent conversation to understand:
+   - What was accomplished
+   - What files were changed
+   - What decisions were made
+   - What blockers were encountered
+   - What should be done next
+
+## SESSION NOTE STRUCTURE
+
+Create a markdown file with this structure:
+
+\`\`\`markdown
+# Session Note - {{title}}
+
+**Date:** {{YYYY-MM-DD}}
+**Project:** {{project_name}}
+
+---
+
+## Summary
+
+{{2-3 sentence summary of what was accomplished}}
+
+## Changes Made
+
+- {{list of files created/modified}}
+- {{features implemented}}
+- {{bugs fixed}}
+
+## Decisions Made
+
+- {{architectural decisions}}
+- {{technology choices}}
+- {{scope changes}}
+
+## Blockers / Issues
+
+- {{problems encountered}}
+- {{unresolved questions}}
+
+## Next Steps
+
+- [ ] {{actionable next task}}
+- [ ] {{follow-up item}}
+
+---
+
+*Generated by /note*
+\`\`\`
+
+## FILE LOCATION
+
+Save the note to:
+- Single repo: \`.compilr/sessions/{{YYYY-MM-DD}}-{{slug}}.md\`
+- Two repo: \`{{project}}-docs/04-session-notes/{{YYYY-MM-DD}}-{{slug}}.md\`
+
+Create the directory if it doesn't exist.
+
+## RULES
+
+1. Use ask_user_simple to ask for a title if not provided
+2. Keep summary concise (2-3 sentences max)
+3. List concrete changes, not vague descriptions
+4. Decisions should explain the "why"
+5. Next steps should be actionable
+6. If user provides a title, use it; otherwise generate one from the summary
+
+## COMPLETION CRITERIA
+✓ Session note file is created
+✓ All sections are filled in
+✓ User has reviewed the note`,
+        tags: ['documentation', 'session'],
+    }),
+    defineSkill({
+        name: 'build',
+        description: 'Implement a backlog item end-to-end',
+        tags: ['implementation', 'coding'],
+        prompt: `You are in BUILD MODE. Implement the specified backlog item.
+
+## ITEM TO IMPLEMENT
+- **ID:** {{item_id}}
+- **Title:** {{item_title}}
+- **Type:** {{item_type}}
+- **Priority:** {{item_priority}}
+- **Description:** {{item_description}}
+
+## BEFORE STARTING
+
+1. Show the item details to the user in a clear format
+2. Use ask_user_simple to confirm: "Proceed with implementation?"
+   - Options: "Yes, let's build it", "No, pick a different item", "Cancel"
+3. If there are dependency warnings, mention them and ask if user wants to proceed anyway
+
+## CONTEXT TO READ
+
+Before implementing, read these files for context:
+- **PRD.md** (if exists): Project vision and requirements
+- **CLAUDE.md**: Coding standards and conventions
+- **Existing code**: Understand patterns already in use
+
+## IMPLEMENTATION WORKFLOW
+
+### Phase 1: Plan
+1. Use todo_write to create implementation checklist:
+   - Break down the item into concrete tasks
+   - Identify files to create or modify
+   - Note any edge cases to handle
+2. Update backlog status to 🚧 using backlog_write
+
+### Phase 2: Implement
+1. Write code following project conventions from CLAUDE.md
+2. Add tests if the project has a test framework
+3. Keep changes focused on the backlog item scope
+4. Use todo_write to track progress through tasks
+
+### Phase 3: Verify
+1. Run tests with run_tests tool
+2. Run lint with run_lint tool
+3. If tests or lint fail:
+   - Analyze the error message
+   - Fix the issue
+   - Re-run verification
+   - Repeat up to 3 times
+4. If still failing after 3 attempts:
+   - Report the issue to user
+   - Keep status as 🚧
+   - Ask for guidance
+
+### Phase 4: Complete
+1. Update backlog status to ✅ using backlog_write
+2. Create git commit with message format:
+   - feat({{item_id}}): {{item_title}} - for features
+   - fix({{item_id}}): {{item_title}} - for bugs
+   - chore({{item_id}}): {{item_title}} - for chores
+3. Update backlog with the commit SHA
+4. Clear todos with todo_write
+5. Summarize what was implemented
+
+## RULES
+
+- Follow coding standards from CLAUDE.md strictly
+- Keep commits atomic - one backlog item per commit
+- Ask user via ask_user_simple if you hit blockers
+- Don't over-engineer - implement exactly what the item describes
+- Don't add features beyond what was requested
+- Use todo_write throughout to show progress
+- Always run tests before marking complete`,
+    }),
+    defineSkill({
+        name: 'scaffold',
+        description: 'Create project foundation based on tech stack',
+        tags: ['setup', 'foundation', 'scaffolding'],
+        prompt: `You are creating the PROJECT SCAFFOLD (foundation).
+
+## PURPOSE
+
+Create the base project structure that features will be built on top of.
+This is the skeleton that makes feature implementation possible.
+
+## CONTEXT TO READ
+
+First, read these files to understand what to build:
+- **CLAUDE.md**: Tech stack, coding standards, project type
+- **PRD.md** (if exists): Project vision and requirements
+- **Existing files**: What already exists (if anything)
+
+## BEFORE STARTING
+
+1. Summarize the detected/specified tech stack
+2. Use ask_user_simple to confirm: "Create project scaffold with this stack?"
+   - Options: "Yes, create it", "No, let me specify", "Cancel"
+3. If user wants to specify, ask about tech stack preferences
+
+## SCAFFOLD BY PROJECT TYPE
+
+### Web Application (React/Vue/Svelte)
+
+Create:
+- \`src/\` folder structure:
+  - \`src/components/\` - Reusable components
+  - \`src/pages/\` or \`src/routes/\` - Page components
+  - \`src/lib/\` or \`src/utils/\` - Utility functions
+  - \`src/styles/\` - Global styles
+- \`package.json\` with dependencies
+- Build config (\`vite.config.ts\`, \`next.config.js\`, etc.)
+- \`index.html\` entry point (if applicable)
+- Basic App component with routing setup
+- CSS/Tailwind configuration
+- \`.gitignore\`
+- \`README.md\` with setup instructions
+
+### API / Backend (Node/Python/Go)
+
+Create:
+- \`src/\` folder structure:
+  - \`src/routes/\` or \`src/api/\` - API endpoints
+  - \`src/services/\` - Business logic
+  - \`src/models/\` - Data models
+  - \`src/utils/\` - Utilities
+- \`package.json\` / \`requirements.txt\` / \`go.mod\`
+- Entry point (\`src/index.ts\`, \`main.py\`, \`main.go\`)
+- Basic server setup (Express, FastAPI, Gin, etc.)
+- Health check endpoint (\`GET /health\`)
+- Environment config (\`.env.example\`)
+- \`.gitignore\`
+- \`README.md\` with setup instructions
+
+### CLI Tool (Node/Python/Rust)
+
+Create:
+- \`src/\` folder structure:
+  - \`src/commands/\` - Command handlers
+  - \`src/utils/\` - Utilities
+- \`package.json\` with \`bin\` entry / \`setup.py\` / \`Cargo.toml\`
+- Entry point with argument parsing
+- Basic command structure (help, version)
+- \`.gitignore\`
+- \`README.md\` with usage instructions
+
+### Full-Stack Application
+
+Create both frontend and backend structures:
+- \`frontend/\` or \`client/\` - Web app scaffold
+- \`backend/\` or \`server/\` - API scaffold
+- Root \`package.json\` with workspace config (if monorepo)
+- \`docker-compose.yml\` (optional)
+- \`.gitignore\`
+- \`README.md\` with setup instructions
+
+## POST-SCAFFOLD STEPS
+
+1. Install dependencies:
+   - \`npm install\` / \`pip install -r requirements.txt\` / etc.
+2. Run build to verify:
+   - \`npm run build\` / equivalent
+3. Run lint to verify:
+   - \`npm run lint\` / equivalent
+4. Create initial git commit:
+   - \`chore: initial project scaffold\`
+5. Update backlog:
+   - Mark scaffold CHORE as ✅ (if exists)
+
+## RULES
+
+- Follow conventions from CLAUDE.md
+- Use modern, widely-adopted patterns
+- Keep it minimal - only what's needed to start
+- Don't add features - just structure
+- Ensure the project builds and lints clean
+- Add helpful comments in config files
+- Include TypeScript/type hints where applicable`,
+    }),
 ];
 /**
  * Default skill registry with built-in skills