forge-workflow 0.0.1

package/docs/AGENT_INSTALL_PROMPT.md

@@ -0,0 +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 docs/WORKFLOW.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