prjct-cli 0.33.5 → 0.35.0

package/templates/agentic/orchestrator.md

@@ -0,0 +1,402 @@
+# Orchestrator - Agent & Skill Coordinator
+
+**Purpose**: Automatically route tasks to the right agents and skills.
+
+## How It Works
+
+```
+User Task → Orchestrator → [Analyze] → [Fragment?] → [Load Agents] → [Delegate] → [Execute]
+```
+
+The orchestrator is **implicit** - it runs automatically for every p. command.
+
+**CRITICAL**: This is an AGENTIC orchestrator. Claude analyzes and decides - NO hardcoded keyword matching.
+
+---
+
+## Step 1: Task Analysis (AGENTIC)
+
+Analyze the current task/command to determine domains involved.
+
+**DO NOT use keyword matching.** Instead, analyze:
+1. What does the task actually require?
+2. What files/modules will be affected?
+3. What expertise is needed?
+
+### Domain Detection (Agentic, Not Keyword-Based)
+
+| Domain | What It Handles | Agent |
+|--------|----------------|-------|
+| **Frontend** | UI components, forms, layouts, styling, client-side logic | `frontend.md` |
+| **UX/UI** | Design systems, accessibility, user experience | `uxui.md` |
+| **Backend** | API endpoints, server logic, business rules, auth | `backend.md` |
+| **Database** | Schema design, migrations, queries, data models | `database.md` |
+| **Testing** | Unit tests, integration tests, e2e tests | `testing.md` |
+| **DevOps** | CI/CD, deployment, infrastructure, containers | `devops.md` |
+
+### Analysis Process (AGENTIC)
+
+```
+1. READ the task description carefully
+2. REASON about what work is actually required
+3. IDENTIFY which domains are involved (can be multiple)
+4. CHECK which agents exist in {agentsDir}
+5. DECIDE: Fragment into subtasks OR single execution
+```
+
+**Remember**: Agents in `{agentsDir}` are ALREADY project-specific. They were generated during `p. sync` with this project's patterns and technologies. Always prefer specialist agents over generalist.
+
+---
+
+## Step 2: Load Project Context
+
+```
+READ: .prjct/prjct.config.json → {projectId}
+SET: {globalPath} = ~/.prjct-cli/projects/{projectId}
+
+READ: {globalPath}/config/skills.json → {skillsConfig}
+READ: {globalPath}/analysis/repo-analysis.json → {repoAnalysis}
+```
+
+---
+
+## Step 3: Load Relevant Agents
+
+For each detected domain, load the corresponding agent.
+
+```
+SET: {loadedAgents} = []
+
+FOR EACH domain IN {detectedDomains}:
+  SET: {agentPath} = {globalPath}/agents/{domain}.md
+
+  IF file exists:
+    READ: {agentPath}
+    EXTRACT: frontmatter (description, skills, patterns)
+    ADD to {loadedAgents}
+
+    OUTPUT: "🤖 Loaded: {domain} agent"
+```
+
+### Agent Context Injection
+
+Each loaded agent provides:
+- **Patterns**: Code patterns specific to this project
+- **Conventions**: Naming, structure, style rules
+- **Skills**: Which skills to invoke for this domain
+- **Anti-patterns**: What to avoid
+
+---
+
+## Step 4: Invoke Skills
+
+For each loaded agent, check if skills should be invoked.
+
+```
+FOR EACH agent IN {loadedAgents}:
+  GET: {agentSkills} = agent.frontmatter.skills
+
+  FOR EACH skillName IN {agentSkills}:
+    SET: {skillPath} = ~/.claude/skills/{skillName}/SKILL.md
+
+    IF file exists:
+      READ: {skillPath}
+      EXTRACT: skill instructions
+      ADD to {activeSkills}
+
+      OUTPUT: "⚡ Skill active: {skillName}"
+```
+
+### Skill Selection Criteria
+
+Only invoke skills that are:
+1. **Relevant** to the current task
+2. **Installed** in ~/.claude/skills/
+3. **Linked** to a loaded agent
+
+---
+
+## Step 5: Build Execution Context
+
+Combine all context for task execution.
+
+```json
+{
+  "task": "{original task description}",
+  "command": "{p. command being executed}",
+  "project": {
+    "id": "{projectId}",
+    "ecosystem": "{repoAnalysis.ecosystem}",
+    "conventions": "{repoAnalysis.conventions}"
+  },
+  "agents": [
+    {
+      "name": "{agent.name}",
+      "patterns": "{agent.patterns}",
+      "rules": "{agent.rules}"
+    }
+  ],
+  "skills": [
+    {
+      "name": "{skill.name}",
+      "instructions": "{skill.instructions}"
+    }
+  ],
+  "execution": {
+    "primaryDomain": "{primaryDomain}",
+    "secondaryDomains": ["{secondaryDomains}"],
+    "commands": "{repoAnalysis.commands}"
+  }
+}
+```
+
+---
+
+## Step 6: Task Fragmentation (AGENTIC)
+
+For complex multi-domain tasks, fragment into subtasks for specialist agents.
+
+**Read**: `templates/agentic/task-fragmentation.md` for full details.
+
+### When to Fragment
+
+Fragment when:
+- Task spans 3+ domains
+- One-shot execution would saturate context
+- Task has natural dependency order (database → backend → frontend)
+
+### Fragmentation Process
+
+```
+1. IDENTIFY atomic subtasks (one domain each)
+2. ASSIGN responsible agent to each subtask
+3. ORDER by dependencies
+4. DELEGATE via Task tool with clean context
+5. COLLECT summaries for context handoff
+```
+
+### Delegation Pattern
+
+For each subtask:
+
+```
+Task(
+  subagent_type: 'general-purpose',
+  prompt: '
+    ## Agent Assignment
+    Read and apply: {agentsPath}/{domain}.md
+
+    ## Subtask
+    {subtask.description}
+
+    ## Previous Subtask Output (if any)
+    {previousSubtask.summary}
+
+    ## MANDATORY: Generate Summary on Completion
+    - What was done
+    - Files created/modified
+    - Output for next agent
+
+    ## FOCUS
+    ONLY this subtask. Do NOT implement other parts.
+  '
+)
+```
+
+### Context Handoff
+
+Each subtask generates a summary stored in `storage/state.json`:
+
+```json
+{
+  "subtasks": [{
+    "id": "subtask-1",
+    "status": "completed",
+    "summary": {
+      "title": "Create auth schema",
+      "description": "Created User and Session models",
+      "outputForNextAgent": "Models available via Prisma"
+    }
+  }]
+}
+```
+
+The summary is passed to the next subtask for context.
+
+---
+
+## Step 7: Execute with Context
+
+Pass the execution context to the command template.
+
+The command template receives:
+- `{orchestrator.agents}` - Loaded agent contexts
+- `{orchestrator.skills}` - Active skill instructions
+- `{orchestrator.project}` - Project conventions
+- `{orchestrator.execution}` - Execution metadata
+
+---
+
+## Multi-Domain Coordination (Example)
+
+When task spans multiple domains, use FRAGMENTATION:
+
+### Example: "Add user authentication with login form"
+
+```
+🎯 Task: add user authentication with login form
+
+📊 Analysis:
+├── Domains detected: database, backend, frontend
+├── Agents available: database.md ✅, backend.md ✅, frontend.md ✅
+└── Fragmentation: REQUIRED (3 domains)
+
+📋 Subtasks (ordered by dependencies):
+│
+├─ 1. [database] Create auth schema
+│     Agent: database.md
+│     Output: User model, Session model, migrations
+│
+├─ 2. [backend] Implement auth API
+│     Agent: backend.md
+│     Depends on: #1
+│     Output: /login, /logout endpoints
+│
+└─ 3. [frontend] Create login form
+      Agent: frontend.md
+      Depends on: #2
+      Output: LoginForm component
+
+🚀 Executing subtasks...
+
+✅ Subtask 1 complete → Summary passed to subtask 2
+✅ Subtask 2 complete → Summary passed to subtask 3
+✅ Subtask 3 complete
+
+📋 Task Complete: All 3 subtasks finished
+```
+
+---
+
+## Orchestrator Output
+
+At the start of each command, output:
+
+```
+🎯 Task: {task description}
+
+📦 Context Loaded:
+├── Agents: {loadedAgents.join(', ')}
+├── Skills: {activeSkills.join(', ')}
+└── Primary: {primaryDomain}
+
+{Continue with command execution...}
+```
+
+---
+
+## Integration with Commands
+
+Every p. command should:
+
+1. **Before execution**: Run orchestrator Steps 1-6 (including fragmentation check)
+2. **During execution**: Use orchestrator context, delegate to specialists
+3. **After execution**: Aggregate subtask results, log which agents were used
+
+### Command Template Integration
+
+```markdown
+# p. {command}
+
+## Step 0: Orchestrator
+
+INCLUDE: templates/agentic/orchestrator.md
+
+Execute orchestrator Steps 1-6 to:
+1. Analyze task (agentic, not keyword-based)
+2. Load project context
+3. Load relevant agents
+4. Invoke skills
+5. Build execution context
+6. Fragment into subtasks if needed
+
+## Step 1: {Command-specific logic}
+
+Use {orchestrator.agents} and {orchestrator.skills} for:
+- Code patterns
+- Conventions
+- Domain expertise
+
+If fragmented, delegate each subtask via Task tool.
+
+{Rest of command...}
+```
+
+---
+
+## Configuration
+
+### Disable Orchestrator
+
+For simple commands that don't need orchestration:
+
+```yaml
+---
+orchestrator: false
+---
+```
+
+### Force Specific Agents
+
+```yaml
+---
+orchestrator:
+  agents: [frontend, testing]
+  skills: [ui-design]
+---
+```
+
+---
+
+## Skill Invocation Patterns
+
+### When to Invoke Skills
+
+| Trigger | Skills to Invoke |
+|---------|------------------|
+| Creating UI component | ui-design, accessibility |
+| Writing API endpoint | api-design, backend-patterns |
+| Database changes | sql-patterns, database-design |
+| Writing tests | test-automation |
+| Deploying | ci-cd, infrastructure |
+| Code review | code-review |
+| Creating documents | pdf, docx, pptx (if installed) |
+
+### Skill Execution
+
+Skills provide:
+1. **Instructions** - How to approach the task
+2. **Examples** - Code/pattern examples
+3. **Checklists** - Quality gates
+4. **References** - Additional documentation
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| No agents found | Use default patterns from repo-analysis |
+| No skills installed | Continue without skills, suggest `p. sync` |
+| Agent file missing | Skip that agent, continue with others |
+| Skill file missing | Skip that skill, log warning |
+
+---
+
+## Logging
+
+Log orchestrator decisions to memory:
+
+```json
+{"ts":"{timestamp}","action":"orchestrator","task":"{task}","agents":["{agents}"],"skills":["{skills}"],"primaryDomain":"{domain}"}
+```

package/templates/agentic/task-fragmentation.md

@@ -0,0 +1,323 @@
+# Task Fragmentation
+
+**Purpose**: Break complex multi-domain tasks into subtasks for specialist agents.
+
+## When to Fragment
+
+Fragment a task when:
+- It spans multiple domains (frontend + backend + database)
+- It would require loading 3+ agents for one-shot execution
+- One-shot implementation would saturate context
+- The task has natural dependency order
+- Complex enough that specialist focus improves quality
+
+## When NOT to Fragment
+
+Keep as single task when:
+- Single domain only
+- Small, focused change
+- Already atomic
+- User explicitly requests one-shot execution
+
+---
+
+## Fragmentation Algorithm
+
+### Input
+
+```
+Task: "{task description}"
+Available Agents: [list from {agentsDir}]
+Project Tech: {from repo-analysis.json}
+```
+
+### Process
+
+#### 1. Parse Intent
+
+What is the user trying to achieve?
+What are the moving parts?
+
+#### 2. Identify Components
+
+| Component | Domain | Indicator Keywords |
+|-----------|--------|-------------------|
+| Data layer changes | database | schema, migration, table, query, model |
+| API changes | backend | endpoint, API, route, controller, auth |
+| UI changes | frontend | component, form, page, UI, layout, styling |
+| Test changes | testing | test, spec, coverage, TDD |
+| Deploy changes | devops | deploy, CI/CD, pipeline, container |
+
+#### 3. Check Agent Availability
+
+For each identified component:
+- Does a matching agent exist in `{agentsDir}`?
+- If YES → Create subtask for that agent
+- If NO → Mark for generalist execution (rare)
+
+**Remember**: Agents in `{agentsDir}` are ALREADY project-specific (generated during `p. sync`). Don't second-guess whether they "match" the technology.
+
+#### 4. Order by Dependencies
+
+Typical dependency order:
+1. **Database** (data models first)
+2. **Backend** (API using models)
+3. **Frontend** (UI using API)
+4. **Testing** (tests for all)
+5. **DevOps** (deploy everything)
+
+#### 5. Create Subtask Objects
+
+```json
+{
+  "subtasks": [
+    {
+      "id": "subtask-1",
+      "description": "Create users table schema",
+      "domain": "database",
+      "agent": "database.md",
+      "dependsOn": [],
+      "expectedOutput": "Migration file created"
+    },
+    {
+      "id": "subtask-2",
+      "description": "Create auth API endpoints",
+      "domain": "backend",
+      "agent": "backend.md",
+      "dependsOn": ["subtask-1"],
+      "expectedOutput": "Auth routes implemented"
+    },
+    {
+      "id": "subtask-3",
+      "description": "Create login form component",
+      "domain": "frontend",
+      "agent": "frontend.md",
+      "dependsOn": ["subtask-2"],
+      "expectedOutput": "Login form component"
+    }
+  ]
+}
+```
+
+---
+
+## Output Format
+
+Report fragmentation plan before executing:
+
+```
+🎯 Task: {original task}
+
+📋 Subtasks (ordered by dependencies):
+├─ 1. [database] Create users table schema
+├─ 2. [backend] Create auth API endpoints
+└─ 3. [frontend] Create login form
+
+🤖 Agents to invoke: database, backend, frontend
+```
+
+---
+
+## Delegation Pattern
+
+For each subtask, delegate via Task tool:
+
+```
+Task(
+  subagent_type: 'general-purpose',
+  prompt: '
+    ## Agent Assignment
+    Read and apply: {agentsPath}/{domain}.md
+
+    ## Subtask
+    {subtask.description}
+
+    ## Dependencies
+    {list completed subtasks and their summaries}
+
+    ## Previous Subtask Output
+    {previousSubtask.summary if available}
+
+    ## Expected Output
+    {subtask.expectedOutput}
+
+    ## MANDATORY: Summary on Completion
+
+    When you complete this subtask, provide a summary:
+
+    ### Summary
+    [1-2 sentence description of what you did]
+
+    ### Files Created/Modified
+    [Table of files with actions]
+
+    ### What Was Done
+    [Numbered list of concrete actions]
+
+    ### Output for Next Agent
+    [What the next agent can use from your work]
+
+    ### Notes for Integration
+    [Any important notes for integration]
+
+    ## IMPORTANT
+    Focus ONLY on this subtask.
+    Do NOT implement other parts.
+    Return when this subtask is complete.
+  '
+)
+```
+
+---
+
+## Summary Storage
+
+After each subtask completes, the summary is stored in `storage/state.json`:
+
+```json
+{
+  "currentTask": {
+    "subtasks": [{
+      "id": "subtask-1",
+      "status": "completed",
+      "summary": {
+        "title": "Create auth schema",
+        "description": "Created database schema for user authentication",
+        "filesChanged": [
+          { "path": "prisma/schema.prisma", "action": "modified" }
+        ],
+        "whatWasDone": [
+          "Added User model",
+          "Added Session model"
+        ],
+        "outputForNextAgent": "User and Session models available via Prisma",
+        "notes": "Use bcrypt for password hashing"
+      }
+    }]
+  }
+}
+```
+
+---
+
+## Context Handoff
+
+Each subsequent subtask receives the previous subtask's summary:
+
+```
+## Previous Subtask Summary (CONTEXT)
+${previousSubtask.summary}
+
+## What's Available
+- User model (prisma.user)
+- Session model (prisma.session)
+- Notes: Use bcrypt for passwords
+
+## Your Task
+Create auth API endpoints using the models from subtask 1.
+```
+
+---
+
+## Progress Tracking
+
+The orchestrator updates progress after each subtask:
+
+```
+📊 Progress: 2/4 subtasks (50%)
+
+✅ 1. [database] Create auth schema
+✅ 2. [backend] Create auth API
+▶️ 3. [frontend] Create login form ← CURRENT
+⏳ 4. [testing] Add auth tests
+```
+
+---
+
+## Aggregating Results
+
+After all subtasks complete, report aggregated status:
+
+```
+✅ Task Complete: add user authentication
+
+📋 Subtasks Completed:
+├─ ✅ 1. [database] Create auth schema
+│      Files: prisma/schema.prisma
+│
+├─ ✅ 2. [backend] Create auth API
+│      Files: src/routes/auth.ts, src/middleware/auth.ts
+│
+├─ ✅ 3. [frontend] Create login form
+│      Files: src/components/LoginForm.tsx
+│
+└─ ✅ 4. [testing] Add auth tests
+       Files: tests/auth.test.ts
+
+📁 Total files affected: 5
+⏱️ Total duration: {calculated from subtask times}
+```
+
+---
+
+## Error Handling
+
+If a subtask fails:
+
+```
+❌ Subtask 2/4 failed: Create auth API
+
+Error: Database connection failed
+
+Options:
+1. Retry this subtask
+2. Skip and continue with remaining subtasks
+3. Abort task and rollback
+
+What would you like to do?
+```
+
+Use `AskUserQuestion` to get user decision on failure handling.
+
+---
+
+## Anti-Patterns to Avoid
+
+### 1. Over-fragmentation
+```
+❌ WRONG: 10 subtasks for "add login button"
+✅ RIGHT: Single task (already atomic)
+```
+
+### 2. Under-fragmentation
+```
+❌ WRONG: 1 subtask for "add complete auth system"
+✅ RIGHT: 4 subtasks (database, backend, frontend, testing)
+```
+
+### 3. Wrong Dependency Order
+```
+❌ WRONG: Frontend before backend (depends on API)
+✅ RIGHT: Database → Backend → Frontend
+```
+
+### 4. Missing Summaries
+```
+❌ WRONG: Subtask completes without summary
+✅ RIGHT: Every subtask generates structured summary
+```
+
+---
+
+## Integration with Storage
+
+The subtasks are stored in `storage/state.json` under `currentTask.subtasks`.
+
+Key methods available:
+- `stateStorage.createSubtasks(projectId, subtasks)` - Create subtasks
+- `stateStorage.completeSubtask(projectId, output, summary)` - Complete current subtask
+- `stateStorage.getCurrentSubtask(projectId)` - Get current subtask
+- `stateStorage.getNextSubtask(projectId)` - Get next subtask
+- `stateStorage.getSubtaskProgress(projectId)` - Get progress
+
+These are called by the orchestrator as subtasks are processed.