agileflow 3.4.2 → 4.0.0-alpha.1

package/src/core/commands/agent.md

@@ -1,256 +0,0 @@
----
-description: Onboard a new agent with profile and contract
-argument-hint: "AGENT_ID=<id> ROLE=<text> [TOOLS=<list>] [SCOPE=<list>]"
-compact_context:
-  priority: high
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:agent - Agent onboarding with profiles and contracts"
-    - "CRITICAL: Create agent profile markdown file at docs/02-practices/prompts/agents/agent-{AGENT_ID}.md"
-    - "CRITICAL: Update roster.yaml at docs/09-agents/roster.yaml with agent metadata"
-    - "MUST include System Prompt (contract) with scope boundaries, commit rules, test requirements"
-    - "MUST use diff-first approach: show preview, get YES/NO confirmation before writing"
-    - "Agent IDs must be descriptive (AG-UI, AG-API, AG-CI) not generic (AG-001)"
-    - "Profile includes: role, tools, scope directories, story tags, contract rules"
-  state_fields:
-    - agent_id
-    - role
-    - tools_list
-    - scope_directories
-    - scope_story_tags
----
-
-# agent-new
-
-Onboard a new agent with profile and system prompt.
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js agent
-```
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `agent` - Onboard new agents with profiles and system prompts (contracts)
-
-**Quick Usage**:
-```
-/agileflow:agent AGENT_ID=AG-UI ROLE="Frontend Developer" TOOLS="Read,Write,Bash" SCOPE="src/components/,US-00*"
-```
-
-**What It Does**: Create agent profile → Update roster → Generate system prompt snippet
-
-### Tool Usage Examples
-
-**Write** (to create agent profile):
-```xml
-<invoke name="Write">
-<parameter name="file_path">/full/path/to/docs/02-practices/prompts/agents/agent-AG-UI.md</parameter>
-<parameter name="content">---
-agent_id: AG-UI
-role: Frontend Developer
-tools: [Read, Write, Edit, Bash, Glob]
-scope:
-  directories: [src/components/, src/pages/]
-  story_tags: [frontend, ui, ux]
----
-
-# AG-UI: Frontend Developer Agent
-
-## Responsibilities
-Build and maintain user interface components...
-
-## System Prompt (Contract)
-**Scope**: Only modify files in src/components/ and src/pages/
-**Testing**: Run `npm test` before committing
-**Commits**: Prefix with "feat(ui):" or "fix(ui):"
-**Status**: Update status.json after completing stories</parameter>
-</invoke>
-```
-
-**Edit** (to update roster.yaml):
-```xml
-<invoke name="Edit">
-<parameter name="file_path">/full/path/to/docs/09-agents/roster.yaml</parameter>
-<parameter name="old_string">agents: []</parameter>
-<parameter name="new_string">agents:
-  - id: AG-UI
-    role: Frontend Developer
-    tools: [Read, Write, Edit, Bash, Glob]
-    scope:
-      directories: [src/components/, src/pages/]
-      story_tags: [frontend, ui, ux]</parameter>
-</invoke>
-```
-
-**AskUserQuestion** (optional, for confirmation):
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{"question": "Create this agent profile?", "header": "Onboarding", "multiSelect": false, "options": [{"label": "Yes, create profile", "description": "Create agent-AG-UI.md and update roster"}, {"label": "No, cancel", "description": "Cancel without creating"}]}]</parameter>
-</invoke>
-```
-
-**Profile Components**:
-- Agent ID (e.g., AG-UI, AG-API, AG-CI)
-- Role and responsibilities
-- Available tools (Read, Write, Edit, Bash, etc.)
-- Scope boundaries (directories, story tags)
-- System prompt (contract with strict rules)
-
-**Best Practices**:
-- Use descriptive agent IDs (AG-UI, AG-API, not AG-001)
-- Define clear scope boundaries to prevent conflicts
-- Include test requirements in contract
-- Map agents to specific story types
-
-<!-- COMPACT_SUMMARY_END -->
-
-## Prompt
-
-ROLE: Agent Onboarder
-
-INPUTS
-AGENT_ID=<AG-UI|AG-API|AG-CI or custom>  ROLE=<role>
-TOOLS=[list]  SCOPE=<directories & story tags>
-
-TEMPLATE
-Use the following agent profile template:
-@packages/cli/src/core/templates/agent-profile-template.md
-
-ACTIONS
-1) Create docs/02-practices/prompts/agents/agent-<AGENT_ID>.md from agent-profile-template.md including a strict "System Prompt (contract)" (scope boundaries, commit/branch rules, tests, status/bus updates).
-2) Update docs/09-agents/roster.yaml (create if missing) mapping id→role/tools/scope.
-3) Print a persona snippet to paste as that terminal's system prompt.
-
-Diff-first; YES/NO.
-
----
-
-## Expected Output
-
-### Successful Agent Onboarding
-
-```
-📋 Onboarding New Agent: AG-UI
-
-AGENT_ID: AG-UI
-ROLE: Frontend Developer
-TOOLS: Read, Write, Edit, Bash, Glob
-SCOPE:
-  - Directories: src/components/, src/pages/
-  - Story Tags: frontend, ui, ux
-
-Files to create:
-───────────────────────────────────────────────
-1. docs/02-practices/prompts/agents/agent-AG-UI.md
-
-Preview:
-─────────────────────────────────────────────
----
-agent_id: AG-UI
-role: Frontend Developer
-tools: [Read, Write, Edit, Bash, Glob]
-scope:
-  directories: [src/components/, src/pages/]
-  story_tags: [frontend, ui, ux]
----
-
-# AG-UI: Frontend Developer Agent
-
-## Responsibilities
-Build and maintain user interface components, pages, and styling.
-
-## System Prompt (Contract)
-**Scope**: Only modify files in src/components/ and src/pages/
-**Testing**: Run `npm test` before committing
-**Commits**: Prefix with "feat(ui):" or "fix(ui):"
-**Status**: Update status.json after completing stories
-─────────────────────────────────────────────
-
-2. docs/09-agents/roster.yaml (update)
-
-   + agents:
-   +   - id: AG-UI
-   +     role: Frontend Developer
-   +     tools: [Read, Write, Edit, Bash, Glob]
-   +     scope:
-   +       directories: [src/components/, src/pages/]
-   +       story_tags: [frontend, ui, ux]
-
-[AskUserQuestion: "Create this agent profile?"]
-
-✅ Agent onboarded successfully!
-   Profile: docs/02-practices/prompts/agents/agent-AG-UI.md
-   Roster: docs/09-agents/roster.yaml updated
-
-📝 System Prompt Snippet (paste into terminal):
-
-You are AG-UI, a Frontend Developer agent.
-Your scope is limited to: src/components/, src/pages/
-You work on stories tagged: frontend, ui, ux
-Always run tests before committing.
-Always update status.json after completing work.
-```
-
-### Missing Required Inputs
-
-```
-❌ Missing required inputs
-
-Please provide:
-  • AGENT_ID - Agent identifier (e.g., AG-UI, AG-API)
-  • ROLE - Agent role description (e.g., "Frontend Developer")
-
-Optional:
-  • TOOLS - Available tools (default: Read, Write, Edit, Bash, Glob)
-  • SCOPE - Directories and story tags
-
-Usage:
-/agileflow:agent AGENT_ID=AG-UI ROLE="Frontend Developer" TOOLS="Read,Write,Edit,Bash,Glob" SCOPE="src/components/,frontend"
-```
-
-### Agent Already Exists
-
-```
-⚠️ Agent already exists: AG-UI
-
-Existing agent profile: docs/02-practices/prompts/agents/agent-AG-UI.md
-
-Options:
-  1. Update existing agent profile
-  2. Create new agent with different ID
-  3. Cancel
-
-[AskUserQuestion: "How to proceed?"]
-```
-
----
-
-## Related Commands
-
-- `/agileflow:configure` - Manage AgileFlow features and hooks
-- `/agileflow:story` - Create user stories for agents
-- `/agileflow:status` - Update story status and progress
-- `/agileflow:babysit` - Interactive mentor workflow
-- `/agileflow:help` - Display AgileFlow overview
-
-### Roster File Created
-
-```
-📋 Onboarding New Agent: AG-API
-
-Note: docs/09-agents/roster.yaml does not exist.
-Creating new roster file.
-
-Files to create:
-───────────────────────────────────────────────
-1. docs/02-practices/prompts/agents/agent-AG-API.md
-2. docs/09-agents/roster.yaml (NEW)
-
-[AskUserQuestion: "Create agent profile and roster?"]
-
-✅ Agent onboarded successfully!
-   Profile: docs/02-practices/prompts/agents/agent-AG-API.md
-   Roster: docs/09-agents/roster.yaml created
-```

package/src/core/commands/api.md

@@ -1,267 +0,0 @@
----
-description: Start REST API server to expose AgileFlow state
-argument-hint: "ACTION=start|stop|status [PORT=3456]"
-compact_context:
-  priority: medium
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:api - REST API server for state exposure"
-    - "API is READ-ONLY (no mutations through API)"
-    - "Default port: 3456, localhost only"
-  state_fields:
-    - server_running
-    - server_port
-    - server_pid
----
-
-# api
-
-Start, stop, or check status of the AgileFlow REST API server.
-
----
-
-## Overview
-
-The API server exposes AgileFlow state (sessions, status, tasks, bus messages) via REST endpoints for external GUI integrations like dashboards.
-
-**Key Principles**:
-- **READ-ONLY**: API exposes state but never mutates it (writes go through CLI)
-- **JSON source of truth**: All data comes from existing JSON files
-- **Localhost-only**: Binds to 127.0.0.1 by default for security
-
----
-
-## Usage
-
-### Start the API Server
-
-```
-/agileflow:api ACTION=start [PORT=3456]
-```
-
-Starts the REST API server on the specified port (default: 3456).
-
-### Stop the API Server
-
-```
-/agileflow:api ACTION=stop
-```
-
-Stops the running API server.
-
-### Check Server Status
-
-```
-/agileflow:api ACTION=status
-```
-
-Shows whether the server is running and on which port.
-
----
-
-## Available Endpoints
-
-Once the server is running, these endpoints are available:
-
-| Endpoint | Description |
-|----------|-------------|
-| `GET /api` | API information and available endpoints |
-| `GET /api/health` | Health check |
-| `GET /api/sessions` | List active sessions |
-| `GET /api/sessions/:id` | Get session by ID |
-| `GET /api/status` | Get status.json (epics/stories state) |
-| `GET /api/tasks` | List tasks (filterable) |
-| `GET /api/tasks/:id` | Get task by ID |
-| `GET /api/bus/messages` | Get bus messages (paginated) |
-| `GET /api/metrics` | Aggregated metrics |
-| `GET /api/epics` | List epics |
-| `GET /api/epics/:id` | Get epic by ID |
-| `GET /api/stories` | List stories (filterable) |
-| `GET /api/stories/:id` | Get story by ID |
-
-### Query Parameters
-
-**GET /api/tasks**:
-- `state`: Filter by state (queued, running, completed, failed, blocked)
-- `story_id`: Filter by story ID
-- `subagent_type`: Filter by agent type
-
-**GET /api/bus/messages**:
-- `limit`: Max messages to return (default: 100)
-- `offset`: Skip first N messages
-- `story_id`: Filter by story ID
-- `from`: Filter by sender agent
-- `since`: Filter by timestamp (ISO string)
-
-**GET /api/stories**:
-- `status`: Filter by status
-- `epic_id`: Filter by epic ID
-- `owner`: Filter by owner
-
----
-
-## Prompt
-
-ROLE: API Server Manager
-
-INPUTS:
-- ACTION=start|stop|status (required)
-- PORT=<number> (optional, default: 3456)
-
-ACTIONS:
-
-**For ACTION=start**:
-1. Check if server is already running (check `.agileflow/api-server.pid`)
-2. If running, report existing server URL
-3. If not running:
-   - Create the API server script
-   - Start server in background
-   - Save PID to `.agileflow/api-server.pid`
-   - Report server URL
-
-**For ACTION=stop**:
-1. Check `.agileflow/api-server.pid` for running server
-2. If running, kill the process
-3. Remove PID file
-4. Report success
-
-**For ACTION=status**:
-1. Check `.agileflow/api-server.pid`
-2. If PID file exists, check if process is alive
-3. Report running/stopped status with URL if running
-
----
-
-## Implementation
-
-### Start Server
-
-```bash
-# Check for existing server
-if [ -f ".agileflow/api-server.pid" ]; then
-  PID=$(cat .agileflow/api-server.pid)
-  if kill -0 "$PID" 2>/dev/null; then
-    echo "API server already running on PID $PID"
-    echo "URL: http://127.0.0.1:${PORT:-3456}/api"
-    exit 0
-  fi
-fi
-
-# Start server
-node -e "
-const { createApiServer, startApiServer } = require('./.agileflow/scripts/lib/api-server-runner');
-const server = createApiServer({ port: ${PORT:-3456} });
-startApiServer(server).then(({ url }) => {
-  console.log('API server started at ' + url);
-}).catch(err => {
-  console.error('Failed to start:', err.message);
-  process.exit(1);
-});
-" &
-
-# Save PID
-echo $! > .agileflow/api-server.pid
-```
-
-### API Server Runner Script
-
-Create `.agileflow/scripts/lib/api-server-runner.js`:
-
-```javascript
-const { createApiServer, startApiServer, stopApiServer } = require('../../lib/api-server');
-
-// Re-export for CLI usage
-module.exports = { createApiServer, startApiServer, stopApiServer };
-
-// If run directly, start server
-if (require.main === module) {
-  const port = parseInt(process.env.PORT || '3456', 10);
-  const server = createApiServer({ port });
-
-  startApiServer(server).then(({ url }) => {
-    console.log(`AgileFlow API running at ${url}`);
-    console.log('Press Ctrl+C to stop');
-  }).catch(err => {
-    console.error('Failed to start server:', err.message);
-    process.exit(1);
-  });
-
-  // Handle shutdown
-  process.on('SIGINT', async () => {
-    console.log('\nShutting down...');
-    await stopApiServer(server);
-    process.exit(0);
-  });
-}
-```
-
----
-
-## Expected Output
-
-### Starting Server
-
-```
-/agileflow:api ACTION=start PORT=3456
-
-Starting AgileFlow API server...
-
-✅ API server started
-   URL: http://127.0.0.1:3456/api
-   PID: 12345
-
-Available endpoints:
-  GET /api           - API information
-  GET /api/health    - Health check
-  GET /api/sessions  - List sessions
-  GET /api/status    - Story/epic state
-  GET /api/tasks     - Task registry
-  GET /api/metrics   - Aggregated metrics
-
-Try: curl http://127.0.0.1:3456/api/status
-```
-
-### Stopping Server
-
-```
-/agileflow:api ACTION=stop
-
-Stopping API server (PID: 12345)...
-
-✅ API server stopped
-```
-
-### Server Status
-
-```
-/agileflow:api ACTION=status
-
-AgileFlow API Server Status
-────────────────────────────
-Status:  Running
-PID:     12345
-URL:     http://127.0.0.1:3456/api
-Uptime:  2h 15m
-
-Endpoints:
-  /api/status    - 42 stories
-  /api/tasks     - 15 tasks
-  /api/sessions  - 3 active
-```
-
----
-
-## Security Notes
-
-- Server binds to **localhost only** (127.0.0.1) by default
-- No authentication required (local access only)
-- All endpoints are **read-only** (no mutations)
-- To expose externally, use a reverse proxy with authentication
-
----
-
-## Related Commands
-
-- `/agileflow:status` - Update story status
-- `/agileflow:board` - Visual kanban board
-- `/agileflow:metrics` - View project metrics
-- `/agileflow:session` - Manage agent sessions