ctx-cc 3.5.0 → 4.1.0

package/workflows/ctx-router.md

@@ -1,485 +0,0 @@
-<purpose>
-Smart router for CTX - understands natural language, detects intent, and routes to the right workflow.
-
-Users don't need to memorize commands. They describe what they want, CTX routes automatically.
-</purpose>
-
-<ui_reference>
-@~/.claude/ctx/references/ui-brand.md
-</ui_reference>
-
-<intent_detection>
-Parse the user's message to detect intent. Check patterns in order:
-
-| Pattern | Intent | Action |
-|---------|--------|--------|
-| "build", "create", "make", "start new", "I want to..." + "app/project/feature" | new-project | Route to init flow |
-| "fix", "bug", "broken", "not working", "error", "crash", "fails" | debug | Route to debug flow |
-| "test", "QA", "check", "accessible", "works?", "validate" | qa | Route to QA flow |
-| "study", "analyze", "understand", "learn", "explore", "what is this", "deeply study" | analyze | Route to map-codebase flow |
-| "improve", "optimize", "better", "enhance", "upgrade", "refactor" | improve | Analyze + suggest improvements |
-| "review", "audit", "security", "ready", "before deploy" | review | Verify flow |
-| "deploy", "ship", "publish", "release", "push", "launch" | ship | Ship flow |
-| "status", "progress", "where", "what's next", "current" | status | Status report |
-| "help", "how", "what can", "commands", "guide" | help | Show help |
-| "continue", "next", "go", "do it" | continue | Read STATE.md and continue |
-
-Store detected intent for routing.
-</intent_detection>
-
-<process>
-
-<step name="verify_ctx_structure" priority="first">
-**MANDATORY FIRST STEP - Execute before anything else:**
-
-```bash
-test -d .ctx && echo "exists" || echo "missing"
-```
-
-Store result:
-- If "exists": CTX is initialized, load state
-- If "missing": CTX not initialized, may need setup
-</step>
-
-<step name="detect_intent">
-Parse user message and detect intent using patterns above.
-
-Output detected intent for routing decision.
-</step>
-
-<step name="route_no_ctx">
-**If NO .ctx/ folder (new user):**
-
-Route by detected intent:
-
-### Intent: new-project
-
-Output:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- CTX ► WELCOME
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-I understood: "{{user_request}}"
-
-You want to build something new. Let's set it up!
-
-───────────────────────────────────────────────────────
-```
-
-Execute /ctx:init inline (don't tell user to run it separately).
-
-### Intent: analyze (study/explore)
-
-Output:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- CTX ► DEEP STUDY
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-I understood: "{{user_request}}"
-
-Before I analyze, let me understand the scope.
-
-───────────────────────────────────────────────────────
-```
-
-**Step 0: Gather context with AskUserQuestion**
-
-Use the AskUserQuestion tool to ask:
-
-```
-AskUserQuestion({
-  questions: [
-    {
-      question: "What type of analysis do you need?",
-      header: "Scope",
-      options: [
-        { label: "Code only", description: "Analyze codebase structure, patterns, and quality" },
-        { label: "Code + Running app", description: "Also browse the running application in browser" },
-        { label: "Full system", description: "Code + App + API testing + Database inspection" }
-      ],
-      multiSelect: false
-    },
-    {
-      question: "Is the application running locally?",
-      header: "Environment",
-      options: [
-        { label: "Yes, running", description: "App is running at localhost or local URL" },
-        { label: "Not yet", description: "I'll start it or you can help me start it" },
-        { label: "Remote/Staging", description: "App is deployed to a remote environment" }
-      ],
-      multiSelect: false
-    }
-  ]
-})
-```
-
-**If user selects "Code + Running app" or "Full system":**
-
-Ask for credentials:
-```
-AskUserQuestion({
-  questions: [
-    {
-      question: "Do you have login credentials for the app?",
-      header: "Access",
-      options: [
-        { label: "Yes, I'll provide them", description: "I have username/password or API keys" },
-        { label: "No auth needed", description: "The app doesn't require login" },
-        { label: "OAuth/SSO only", description: "Login requires external provider" }
-      ],
-      multiSelect: false
-    }
-  ]
-})
-```
-
-**If user will provide credentials:**
-
-Output:
-```
-╔═══════════════════════════════════════════════════════╗
-║  LOGIN CREDENTIALS                                    ║
-╚═══════════════════════════════════════════════════════╝
-
-I'll detect the app URL from your config files.
-Please provide login credentials for browser testing:
-
-• Username/Email: _______________
-• Password: _______________
-
-───────────────────────────────────────────────────────
-→ Paste credentials or type "skip" to analyze code only
-───────────────────────────────────────────────────────
-```
-
-Store credentials in memory for browser testing (never write to files).
-
-**Detect app URL from codebase:**
-
-```bash
-# Check common locations for app URL
-grep -r "localhost\|127.0.0.1" .env* package.json 2>/dev/null | head -5
-grep -r "PORT\|port" .env* package.json 2>/dev/null | head -5
-```
-
-Extract URL like `http://localhost:3000` from config.
-
-**Step 1: Show analysis plan**
-
-Output:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- CTX ► ANALYZING CODEBASE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Analysis scope: {{selected_scope}}
-Environment: {{selected_environment}}
-Access: {{access_level}}
-
-Starting analysis with 4 specialized mappers...
-
-───────────────────────────────────────────────────────
-```
-
-**Step 2: Create structure**
-
-```bash
-mkdir -p .ctx/codebase
-```
-
-**Step 2: Show spawning indicator**
-
-Output:
-```
-◆ Spawning 4 mappers in parallel...
-  → ctx-tech-mapper
-  → ctx-arch-mapper
-  → ctx-quality-mapper
-  → ctx-concerns-mapper
-```
-
-**Step 3: Spawn 4 mapper agents in parallel**
-
-Read model profile (default to "balanced"):
-```bash
-MODEL_PROFILE="haiku"
-```
-
-Spawn all 4 agents with a SINGLE message containing multiple Task calls:
-
-```
-Task(prompt="Analyze this codebase for technology stack. Write comprehensive analysis to: .ctx/codebase/TECH.md. Include languages, frameworks, dependencies, versions, build tools. Return confirmation with line count when complete.", subagent_type="ctx-tech-mapper", model="haiku", run_in_background=true, description="Map tech stack")
-
-Task(prompt="Analyze this codebase architecture. Write comprehensive analysis to: .ctx/codebase/ARCH.md. Include architectural pattern, layer structure, module boundaries, entry points, data flow. Return confirmation with line count when complete.", subagent_type="ctx-arch-mapper", model="haiku", run_in_background=true, description="Map architecture")
-
-Task(prompt="Analyze this codebase for quality patterns. Write comprehensive analysis to: .ctx/codebase/QUALITY.md. Include test coverage, linting, type safety, documentation, code smells. Return confirmation with line count when complete.", subagent_type="ctx-quality-mapper", model="haiku", run_in_background=true, description="Map quality")
-
-Task(prompt="Analyze this codebase for concerns and risks. Write comprehensive analysis to: .ctx/codebase/CONCERNS.md. Include security issues, technical debt, performance problems, operational risks. Return confirmation with line count when complete.", subagent_type="ctx-concerns-mapper", model="haiku", run_in_background=true, description="Map concerns")
-```
-
-**Step 4: Wait for completion and show progress**
-
-Use TaskOutput to wait for each agent. As each completes, output:
-
-```
-✓ ctx-tech-mapper complete: TECH.md ({{N}} lines)
-✓ ctx-arch-mapper complete: ARCH.md ({{N}} lines)
-✓ ctx-quality-mapper complete: QUALITY.md ({{N}} lines)
-✓ ctx-concerns-mapper complete: CONCERNS.md ({{N}} lines)
-```
-
-**Step 5: Verify output**
-
-```bash
-ls -la .ctx/codebase/
-wc -l .ctx/codebase/*.md
-```
-
-**Step 6: Create summary**
-
-Read all 4 documents:
-```bash
-cat .ctx/codebase/TECH.md
-cat .ctx/codebase/ARCH.md
-cat .ctx/codebase/QUALITY.md
-cat .ctx/codebase/CONCERNS.md
-```
-
-Write `.ctx/codebase/SUMMARY.md` with key findings from each document.
-
-**Step 7: Browser testing (if scope includes running app)**
-
-If user selected "Code + Running app" or "Full system":
-
-Output:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- CTX ► BROWSER TESTING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Now testing the running application...
-
-───────────────────────────────────────────────────────
-```
-
-Use Playwright MCP tools to:
-
-1. Navigate to app URL:
-```
-mcp__playwright__browser_navigate({ url: "{{app_url}}" })
-```
-
-2. Take snapshot of initial state:
-```
-mcp__playwright__browser_snapshot({})
-```
-
-3. If credentials provided, log in:
-```
-mcp__playwright__browser_type({ element: "email/username field", ref: "{{ref}}", text: "{{username}}" })
-mcp__playwright__browser_type({ element: "password field", ref: "{{ref}}", text: "{{password}}" })
-mcp__playwright__browser_click({ element: "login button", ref: "{{ref}}" })
-```
-
-4. Take snapshot after login:
-```
-mcp__playwright__browser_snapshot({})
-```
-
-5. Explore key pages based on codebase analysis:
-   - Navigate to pages identified in ARCH.md
-   - Take screenshots of main flows
-   - Check for console errors
-
-6. Write browser findings to `.ctx/codebase/BROWSER.md`:
-   - Pages tested
-   - UI issues found
-   - Console errors
-   - Accessibility observations
-   - Screenshots taken
-
-Output progress:
-```
-◆ Testing application...
-  → Navigating to {{app_url}}
-  → Logging in as {{username}}
-  → Exploring dashboard
-  → Checking user flows
-
-✓ Browser testing complete: BROWSER.md ({{N}} lines)
-```
-
-**Step 8: Show completion banner**
-
-Output:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- CTX ► MAPPING COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-┌─────────────────────────────────────────────────────┐
-│  CODEBASE SUMMARY                                   │
-├─────────────────────────────────────────────────────┤
-│  Tech:         {{primary_language}}, {{framework}} │
-│  Architecture: {{pattern}}                          │
-│  Quality:      {{coverage}}% coverage, {{warnings}} │
-│  Concerns:     {{concern_count}} identified         │
-└─────────────────────────────────────────────────────┘
-
-Files created:
-  .ctx/codebase/TECH.md
-  .ctx/codebase/ARCH.md
-  .ctx/codebase/QUALITY.md
-  .ctx/codebase/CONCERNS.md
-  .ctx/codebase/SUMMARY.md
-
-───────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Initialize project** — set up CTX workflow with this context
-
-`/ctx:init`
-
-<sub>`/clear` first → fresh context window</sub>
-
-───────────────────────────────────────────────────────
-
-**Also available:**
-- `cat .ctx/codebase/SUMMARY.md` — view full summary
-- `/ctx:map-codebase --refresh` — re-analyze codebase
-
-───────────────────────────────────────────────────────
-```
-
-### Intent: debug
-
-Output:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- CTX ► DEBUG MODE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-I understood: "{{problem_description}}"
-
-Let me analyze the codebase first, then investigate.
-
-───────────────────────────────────────────────────────
-```
-
-First map codebase (same as analyze), then spawn debugger agent.
-
-### Intent: help or unknown
-
-Output:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- CTX ► WELCOME
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-What would you like to do?
-
-┌─────────────────────────────────────────────────────┐
-│  AVAILABLE ACTIONS                                  │
-├─────────────────────────────────────────────────────┤
-│  "Build something new"   → Set up your project      │
-│  "Fix a bug"             → Debug the issue          │
-│  "Study the codebase"    → Analyze everything       │
-│  "Test the app"          → Run full QA              │
-└─────────────────────────────────────────────────────┘
-
-Just describe what you want in natural language!
-
-───────────────────────────────────────────────────────
-```
-</step>
-
-<step name="route_with_ctx">
-**If .ctx/ folder EXISTS:**
-
-### Load state first
-
-```bash
-cat .ctx/STATE.md
-cat .ctx/config.json 2>/dev/null || echo "{}"
-```
-
-Extract:
-- `status`: Current workflow status
-- `currentPhase`: Active phase
-- `profile`: Model profile (quality/balanced/budget)
-
-### Route by Intent + State
-
-| Intent | Action |
-|--------|--------|
-| new-project | Warn project exists, offer to add phase |
-| analyze | Run map-codebase (refresh) |
-| debug | Spawn debugger with context |
-| qa | Spawn QA agent |
-| status | Show status from STATE.md |
-| continue | Resume from STATE.md status |
-
-### Status Report Format
-
-Output:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- CTX ► STATUS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Project: {{name}}
-Status:  {{status}}
-Profile: {{profile}}
-
-Progress: ████████░░ {{percent}}%
-
-| Phase | Status | Tasks    |
-|-------|--------|----------|
-| 1     | ✓      | 5/5      |
-| 2     | ◆      | 2/4      |
-| 3     | ○      | 0/3      |
-
-Current: {{current_phase}}
-
-───────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**{{next_action}}**
-
-`/ctx` or describe what you want to do
-
-───────────────────────────────────────────────────────
-```
-</step>
-
-</process>
-
-<research_integration>
-**When to use ArguSeek:**
-
-For debug, improve, and review intents, research BEFORE spawning agents:
-
-```
-mcp__arguseek__research_iteratively({
-  query: "{{tech_stack}} {{problem_or_goal}} best practices solutions 2025"
-})
-```
-
-Include research findings in agent prompts.
-</research_integration>
-
-<success_criteria>
-- [ ] .ctx structure checked first
-- [ ] Intent detected from user message
-- [ ] Correct flow routed
-- [ ] UI patterns used consistently (banners, boxes, progress)
-- [ ] ArguSeek called for research-worthy intents
-- [ ] Task() agents spawned with full context
-- [ ] STATE.md created/updated
-- [ ] Clear "Next Up" shown with command
-- [ ] User knows to run /ctx to continue
-</success_criteria>