forge-workflow 0.0.4 → 0.0.5

package/docs/AGENT_INSTALL_PROMPT.md

@@ -1,342 +1,342 @@
-# Forge Setup - AI Agent Installation Prompt
-
-**For AI Agents**: This is a step-by-step guide to help you install Forge workflow in the user's project. Follow these instructions carefully to ensure proper setup.
-
----
-
-## Your Task
-
-Help the user install Forge - a TDD-first development workflow system. You will:
-1. Detect project context (framework, language, CI/CD)
-2. Run installation command
-3. Verify setup
-4. Guide the user on next steps
-
----
-
-## Step 1: Detect Agent Type
-
-First, determine which AI agent you are by checking for these directories:
-
-```bash
-# Check for agent-specific directories
-ls -la | grep -E "\.claude|\.cursor|\.cline"
-```
-
-**Agent Detection:**
-- `.claude/` exists → You are **Claude Code**
-- `.cursor/` exists → You are **Cursor**
-- `.cline/` exists → You are **Cline**
-- None exist → Generic agent
-
-Store this for later: `DETECTED_AGENT=<name>`
-
----
-
-## Step 2: Gather Project Context
-
-Explore the project to understand its structure:
-
-### Framework Detection
-```bash
-# Check package.json for framework
-cat package.json | grep -E "next|react|vue|express|fastify"
-```
-
-### Language Detection
-```bash
-# Check for TypeScript
-ls | grep -E "tsconfig.json"
-# Check package.json devDependencies
-cat package.json | grep typescript
-```
-
-### CI/CD Detection
-```bash
-# Check for CI/CD systems
-ls -la .github/workflows/
-ls -la .gitlab-ci.yml
-```
-
-### Git Statistics
-```bash
-# Check project maturity
-git rev-list --count HEAD  # Commit count
-git tag                     # Releases
-```
-
-**Store findings:**
-- Framework: `<Next.js|React|Vue|Express|Unknown>`
-- Language: `<typescript|javascript>`
-- CI/CD: `<GitHub Actions|GitLab CI|None>`
-- Commits: `<count>`
-- Stage: `<new|active|stable>` (based on commits)
-
----
-
-## Step 3: Ask User Questions (Optional)
-
-If auto-detection has low confidence, ask the user:
-
-**Core Questions (3):**
-1. "What is this project about in one sentence?"
-2. "What are you currently working on?"
-3. "Confirm detected project stage: `<detected>`?"
-
-**Optional Questions (only if needed):**
-4. "Primary programming language?"
-5. "Main framework/tech stack?"
-
----
-
-## Step 4: Run Installation
-
-Execute the Forge setup command with detected agent:
-
-```bash
-bunx forge setup --agents $DETECTED_AGENT
-```
-
-**Expected Output:**
-- `AGENTS.md` created or updated
-- `.forge/context.json` created with auto-detected info
-- Instructions displayed for next steps
-
-**If command fails:**
-- Check Node.js version: `node --version` (need v18+)
-- Try with bunx: `bunx forge@latest setup --agents $DETECTED_AGENT`
-- Report error to user with instructions to check `https://github.com/your-repo/issues`
-
----
-
-## Step 5: Verify Setup
-
-Check that files were created properly:
-
-```bash
-# Verify core files exist
-test -f AGENTS.md && echo "✓ AGENTS.md created"
-test -f .forge/context.json && echo "✓ Context saved"
-
-# Show what was created
-cat .forge/context.json
-```
-
-**Expected context.json structure:**
-```json
-{
-  "auto_detected": {
-    "framework": "Next.js",
-    "language": "typescript",
-    "stage": "active",
-    "confidence": 0.85
-  },
-  "user_provided": {
-    "description": "...",
-    "current_work": "..."
-  }
-}
-```
-
----
-
-## Step 6: Customize AGENTS.md (Optional Enhancement)
-
-If you gathered rich context in Step 2, enhance the generated AGENTS.md:
-
-### Add Project-Specific Sections
-
-Look for the `<!-- USER:START -->` marker and add:
-
-```markdown
-## Project Context
-
-**Framework**: Next.js 14 with App Router
-**Language**: TypeScript (strict mode)
-**Database**: PostgreSQL with Prisma ORM
-**Testing**: Jest + React Testing Library
-**CI/CD**: GitHub Actions (main branch protected)
-
-## Architecture Notes
-
-- Frontend: React Server Components
-- API: Next.js API routes + tRPC
-- Auth: NextAuth.js with JWT sessions
-```
-
-**IMPORTANT:**
-- Only add facts discovered during exploration
-- Do NOT make up information
-- Keep additions inside `<!-- USER:START -->` / `<!-- USER:END -->` markers
-
----
-
-## Step 7: Report Results
-
-Summarize what was completed for the user:
-
-```
-✅ Forge Installation Complete
-
-**What was created:**
-- AGENTS.md: Workflow configuration for AI agents
-- .forge/context.json: Project context storage
-
-**Auto-detected:**
-- Framework: <detected-framework>
-- Language: <detected-language>
-- Stage: <detected-stage>
-
-**Next Steps:**
-
-1. Review AGENTS.md to understand the workflow
-2. Run `/status` to see current project state
-3. Start your first task:
-   - Feature: `/plan <feature-name>` → `/dev`
-   - Bug fix: `/dev` (write failing test first)
-   - Docs: `/verify` → `/ship`
-
-**Quick Start Commands:**
-- `/status` - Check current context
-- `/plan <feature-slug>` - Design + research + implementation plan
-- `/dev` - Start TDD development
-
-**Need help?** Check AGENTS.md for full guide
-```
-
----
-
-## Step 8: Offer to Run /status
-
-Ask the user:
-
-> "Would you like me to run `/status` now to check the project state and show you what's available to work on?"
-
-If yes → Run the `/status` skill/command
-
----
-
-## Safety Guardrails
-
-**DO:**
-- ✅ Read files to understand project structure
-- ✅ Run safe commands (ls, cat, grep, git status)
-- ✅ Ask user for confirmation before installation
-- ✅ Verify files were created successfully
-- ✅ Report what changed
-
-**DON'T:**
-- ❌ Run destructive commands (rm, mv, git reset)
-- ❌ Modify existing files without asking
-- ❌ Push to remote repositories
-- ❌ Make up project information
-- ❌ Skip verification steps
-
----
-
-## Troubleshooting
-
-### Installation Fails
-
-**Error: "Command not found: npx"**
-- Solution: Install Node.js v18+ from https://nodejs.org/
-
-**Error: "AGENTS.md already exists"**
-- Solution: Offer user options:
-  1. Intelligent merge (preserves their content)
-  2. Keep existing (skip installation)
-  3. Backup and replace
-
-```bash
-# Backup existing file
-cp AGENTS.md AGENTS.md.backup
-# Then retry installation
-bunx forge setup --merge=smart --agents $DETECTED_AGENT
-```
-
-**Error: "Permission denied"**
-- Solution: Check write permissions in directory
-
-### Context Detection Issues
-
-**Low confidence (<0.6)**
-- Ask user the 3 core questions
-- Document answers in `.forge/context.json` manually:
-
-```bash
-# Update context with user input
-cat > .forge/context.json <<EOF
-{
-  "user_provided": {
-    "description": "<user-answer-1>",
-    "current_work": "<user-answer-2>"
-  }
-}
-EOF
-```
-
----
-
-## Example Full Conversation
-
-**User:** "I want to set up Forge in my project"
-
-**Agent (You):**
-
-> I'll help you set up Forge! Let me first explore your project to understand its structure.
->
-> *[Runs detection commands...]*
->
-> I detected:
-> - Framework: **Next.js**
-> - Language: **TypeScript**
-> - CI/CD: **GitHub Actions**
-> - Stage: **Active** (150 commits, CI/CD configured)
-> - Agent: **Claude Code** (detected from .claude/ directory)
->
-> This looks correct?
-
-**User:** "Yes"
-
-**Agent:**
-
-> Great! Running installation...
->
-> *[Executes: `bunx forge setup --agents claude-code`]*
->
-> ✅ **Installation Complete!**
->
-> Created:
-> - `AGENTS.md` - Your workflow configuration
-> - `.forge/context.json` - Project context storage
->
-> **Next steps:**
-> 1. Review AGENTS.md to understand the workflow
-> 2. Try `/status` to see current project state
->
-> Would you like me to run `/status` now?
-
----
-
-## Notes for AI Agents
-
-- **Be conversational**: This is an interactive process, not a script
-- **Show progress**: Use emojis (✅, 🔍, ⚙️) to make it engaging
-- **Ask when unsure**: Better to ask than guess wrong
-- **Verify everything**: Don't assume - check that files were created
-- **Be helpful**: Offer to run `/status` or create first issue
-
-**This prompt is designed to work with:**
-- Claude Code (via CLI)
-- Cursor (via chat)
-- Cline (via VSCode extension)
-- Any AI coding assistant with file system access
-
----
-
-## Version
-
-**Forge Setup Prompt v1.6.0**
-Last updated: 2026-02-06
-
-For issues or improvements, report at: https://github.com/your-repo/issues
+# Forge Setup - AI Agent Installation Prompt
+
+**For AI Agents**: This is a step-by-step guide to help you install Forge workflow in the user's project. Follow these instructions carefully to ensure proper setup.
+
+---
+
+## Your Task
+
+Help the user install Forge - a TDD-first development workflow system. You will:
+1. Detect project context (framework, language, CI/CD)
+2. Run installation command
+3. Verify setup
+4. Guide the user on next steps
+
+---
+
+## Step 1: Detect Agent Type
+
+First, determine which AI agent you are by checking for these directories:
+
+```bash
+# Check for agent-specific directories
+ls -la | grep -E "\.claude|\.cursor|\.cline"
+```
+
+**Agent Detection:**
+- `.claude/` exists → You are **Claude Code**
+- `.cursor/` exists → You are **Cursor**
+- `.cline/` exists → You are **Cline**
+- None exist → Generic agent
+
+Store this for later: `DETECTED_AGENT=<name>`
+
+---
+
+## Step 2: Gather Project Context
+
+Explore the project to understand its structure:
+
+### Framework Detection
+```bash
+# Check package.json for framework
+cat package.json | grep -E "next|react|vue|express|fastify"
+```
+
+### Language Detection
+```bash
+# Check for TypeScript
+ls | grep -E "tsconfig.json"
+# Check package.json devDependencies
+cat package.json | grep typescript
+```
+
+### CI/CD Detection
+```bash
+# Check for CI/CD systems
+ls -la .github/workflows/
+ls -la .gitlab-ci.yml
+```
+
+### Git Statistics
+```bash
+# Check project maturity
+git rev-list --count HEAD  # Commit count
+git tag                     # Releases
+```
+
+**Store findings:**
+- Framework: `<Next.js|React|Vue|Express|Unknown>`
+- Language: `<typescript|javascript>`
+- CI/CD: `<GitHub Actions|GitLab CI|None>`
+- Commits: `<count>`
+- Stage: `<new|active|stable>` (based on commits)
+
+---
+
+## Step 3: Ask User Questions (Optional)
+
+If auto-detection has low confidence, ask the user:
+
+**Core Questions (3):**
+1. "What is this project about in one sentence?"
+2. "What are you currently working on?"
+3. "Confirm detected project stage: `<detected>`?"
+
+**Optional Questions (only if needed):**
+4. "Primary programming language?"
+5. "Main framework/tech stack?"
+
+---
+
+## Step 4: Run Installation
+
+Execute the Forge setup command with detected agent:
+
+```bash
+bunx forge setup --agents $DETECTED_AGENT
+```
+
+**Expected Output:**
+- `AGENTS.md` created or updated
+- `.forge/context.json` created with auto-detected info
+- Instructions displayed for next steps
+
+**If command fails:**
+- Check Node.js version: `node --version` (need v18+)
+- Try with bunx: `bunx forge@latest setup --agents $DETECTED_AGENT`
+- Report error to user with instructions to check `https://github.com/your-repo/issues`
+
+---
+
+## Step 5: Verify Setup
+
+Check that files were created properly:
+
+```bash
+# Verify core files exist
+test -f AGENTS.md && echo "✓ AGENTS.md created"
+test -f .forge/context.json && echo "✓ Context saved"
+
+# Show what was created
+cat .forge/context.json
+```
+
+**Expected context.json structure:**
+```json
+{
+  "auto_detected": {
+    "framework": "Next.js",
+    "language": "typescript",
+    "stage": "active",
+    "confidence": 0.85
+  },
+  "user_provided": {
+    "description": "...",
+    "current_work": "..."
+  }
+}
+```
+
+---
+
+## Step 6: Customize AGENTS.md (Optional Enhancement)
+
+If you gathered rich context in Step 2, enhance the generated AGENTS.md:
+
+### Add Project-Specific Sections
+
+Look for the `<!-- USER:START -->` marker and add:
+
+```markdown
+## Project Context
+
+**Framework**: Next.js 14 with App Router
+**Language**: TypeScript (strict mode)
+**Database**: PostgreSQL with Prisma ORM
+**Testing**: Jest + React Testing Library
+**CI/CD**: GitHub Actions (main branch protected)
+
+## Architecture Notes
+
+- Frontend: React Server Components
+- API: Next.js API routes + tRPC
+- Auth: NextAuth.js with JWT sessions
+```
+
+**IMPORTANT:**
+- Only add facts discovered during exploration
+- Do NOT make up information
+- Keep additions inside `<!-- USER:START -->` / `<!-- USER:END -->` markers
+
+---
+
+## Step 7: Report Results
+
+Summarize what was completed for the user:
+
+```
+✅ Forge Installation Complete
+
+**What was created:**
+- AGENTS.md: Workflow configuration for AI agents
+- .forge/context.json: Project context storage
+
+**Auto-detected:**
+- Framework: <detected-framework>
+- Language: <detected-language>
+- Stage: <detected-stage>
+
+**Next Steps:**
+
+1. Review AGENTS.md to understand the workflow
+2. Run `/status` to see current project state
+3. Start your first task:
+   - Feature: `/plan <feature-name>` → `/dev`
+   - Bug fix: `/dev` (write failing test first)
+   - Docs: `/verify` → `/ship`
+
+**Quick Start Commands:**
+- `/status` - Check current context
+- `/plan <feature-slug>` - Design + research + implementation plan
+- `/dev` - Start TDD development
+
+**Need help?** Check AGENTS.md for full guide
+```
+
+---
+
+## Step 8: Offer to Run /status
+
+Ask the user:
+
+> "Would you like me to run `/status` now to check the project state and show you what's available to work on?"
+
+If yes → Run the `/status` skill/command
+
+---
+
+## Safety Guardrails
+
+**DO:**
+- ✅ Read files to understand project structure
+- ✅ Run safe commands (ls, cat, grep, git status)
+- ✅ Ask user for confirmation before installation
+- ✅ Verify files were created successfully
+- ✅ Report what changed
+
+**DON'T:**
+- ❌ Run destructive commands (rm, mv, git reset)
+- ❌ Modify existing files without asking
+- ❌ Push to remote repositories
+- ❌ Make up project information
+- ❌ Skip verification steps
+
+---
+
+## Troubleshooting
+
+### Installation Fails
+
+**Error: "Command not found: npx"**
+- Solution: Install Node.js v18+ from https://nodejs.org/
+
+**Error: "AGENTS.md already exists"**
+- Solution: Offer user options:
+  1. Intelligent merge (preserves their content)
+  2. Keep existing (skip installation)
+  3. Backup and replace
+
+```bash
+# Backup existing file
+cp AGENTS.md AGENTS.md.backup
+# Then retry installation
+bunx forge setup --merge=smart --agents $DETECTED_AGENT
+```
+
+**Error: "Permission denied"**
+- Solution: Check write permissions in directory
+
+### Context Detection Issues
+
+**Low confidence (<0.6)**
+- Ask user the 3 core questions
+- Document answers in `.forge/context.json` manually:
+
+```bash
+# Update context with user input
+cat > .forge/context.json <<EOF
+{
+  "user_provided": {
+    "description": "<user-answer-1>",
+    "current_work": "<user-answer-2>"
+  }
+}
+EOF
+```
+
+---
+
+## Example Full Conversation
+
+**User:** "I want to set up Forge in my project"
+
+**Agent (You):**
+
+> I'll help you set up Forge! Let me first explore your project to understand its structure.
+>
+> *[Runs detection commands...]*
+>
+> I detected:
+> - Framework: **Next.js**
+> - Language: **TypeScript**
+> - CI/CD: **GitHub Actions**
+> - Stage: **Active** (150 commits, CI/CD configured)
+> - Agent: **Claude Code** (detected from .claude/ directory)
+>
+> This looks correct?
+
+**User:** "Yes"
+
+**Agent:**
+
+> Great! Running installation...
+>
+> *[Executes: `bunx forge setup --agents claude-code`]*
+>
+> ✅ **Installation Complete!**
+>
+> Created:
+> - `AGENTS.md` - Your workflow configuration
+> - `.forge/context.json` - Project context storage
+>
+> **Next steps:**
+> 1. Review AGENTS.md to understand the workflow
+> 2. Try `/status` to see current project state
+>
+> Would you like me to run `/status` now?
+
+---
+
+## Notes for AI Agents
+
+- **Be conversational**: This is an interactive process, not a script
+- **Show progress**: Use emojis (✅, 🔍, ⚙️) to make it engaging
+- **Ask when unsure**: Better to ask than guess wrong
+- **Verify everything**: Don't assume - check that files were created
+- **Be helpful**: Offer to run `/status` or create first issue
+
+**This prompt is designed to work with:**
+- Claude Code (via CLI)
+- Cursor (via chat)
+- Cline (via VSCode extension)
+- Any AI coding assistant with file system access
+
+---
+
+## Version
+
+**Forge Setup Prompt v1.6.0**
+Last updated: 2026-02-06
+
+For issues or improvements, report at: https://github.com/your-repo/issues