337 Agents F50485aa

Stage Execution & Protocols

Module Context: Detailed execution protocols for the 4-stage workflow. Referenced by root AGENTS.md.

Stage 1: Sam (Requirements Analysis)

Invoke: sam-analyst
Input:
  - user_request: Original user message
  - fast_mode: true/false from Phase 1
Output: ./temp/skillful-session/sam-draft.md
Confirmation: If fast_mode=false, show draft and request approval
State Update: current_stage = "sam_complete"

Pre-check: None (first stage)

Verification:

test -f ./temp/skillful-session/sam-draft.md || echo "Error: sam-draft.md missing"

Stage 2: Jenny (Detailed Design)

Invoke: jenny-engineer
Input: Read ./temp/skillful-session/sam-draft.md
Context: ./context/anthropic-*.md
Skills: agent-design, skill-design, anthropic-reference
Output: ./temp/skillful-session/jenny-draft.md
Confirmation: Required (unless fast_mode=true)
State Update: current_stage = "jenny_complete"

Pre-check: sam-draft.md must exist

Verification:

test -f ./temp/skillful-session/jenny-draft.md || echo "Error: jenny-draft.md missing"

Stage 3: Will (Quality Review)

Invoke: will-reviewer
Input: Read ./temp/skillful-session/jenny-draft-approved.md
Context: ./context/anthropic-*.md (validation)
Skills: quality-checklist, agent-design, skill-design

Process:
1. Validate jenny-draft-approved.md integrity (check hash)
2. Classify issues: Category 1 (auto-fix) / 2 (design) / 3 (requirement)
3. Apply Category 1 fixes -> will-fixes.md
4. If Category 2: Generate will-feedback.md, ask user decision
5. If Category 3: AskUserQuestion
6. Output: ./temp/skillful-session/will-approved.json

State Update: current_stage = "will_complete"

Pre-check: jenny-draft.md + user approval (unless fast_mode)

Stage 4: Tom (Output Generation)

Invoke: tom-builder
Input: ./temp/skillful-session/will-approved.json
Skills: project-scaffolding, agent-design, skill-design
Output: 
  - ./outputs/{system-name}-start-prompt.md
  - ./outputs/{system-name}/ (project files)
State Update: current_stage = "complete"

Jenny Review Protocol

Trigger: After Jenny completes jenny-draft.md (unless fast_mode=true)

Process:

1. Generate Summary (jenny-summary.md):

   • System Overview: name, purpose, agent/skill counts
   • Agent Structure: role, tools, skills per agent
   • Skill Definitions: purpose, trigger pattern, tools
   • Key Design Decisions: rationale for architectural choices
   • User Review Points: checklist for approval

2. Display to User:

   • Keep under 50 lines
   • Emphasize action commands

3. Handle Response:

4. On Approval:
   • Create locked copy: jenny-draft-approved.md (chmod 444)
   • Generate integrity hash
   • Update session.json: current_stage = "jenny_approved"
   • Proceed to Will immediately

Will-Jenny Feedback Loop

Purpose: Enable Will to request redesign for structural issues while preventing infinite loops.

3-Category Issue Classification

Loop Control

{
  "will_jenny_loop": {
    "max_iterations": 3,
    "current_iteration": 0
  }
}

Enforcement:

• After 3 iterations: Stop loop, escalate to user
• Options: Use v1 (approved) / Use latest / Restart from Sam

Structured Feedback Format

# will-feedback.md
---
format_version: 1.0
revision_scope: SURGICAL
max_changes: 1
---

## Issue: [Description]
**Severity**: high/medium/low
**Confidence**: 0.0-1.0

**Scope**:
  agents: ["affected-agent"]
  skills: []
  workflow: false

**Current State**:
  [field and value]

**Required Change**:
  [new value]

**Constraints**:
- DO NOT modify other agents
- ONLY update specified field

User Decision Points

After Category 2 Issues Found:

Will found design issues

Issue: [Description]
Severity: High | Confidence: 85%
Problem: [explanation]
Impact: [consequences]
Suggestion: [recommended fix]

Options:
1. Ignore and proceed (faster)
2. Request Jenny revision (improves quality)
3. View details (see will-feedback.md)

After Max Iterations Reached:

Design improvement limit reached (3 iterations)

Available Versions:
- v1: User-approved original
- v3: Latest revision

Options:
1. Use v1 (recommended)
2. Use v3
3. Restart from Sam
4. Manual intervention

Fast Mode Behavior

When fast_mode=true:

• Skip Sam questions, immediate draft
• Skip Jenny review (no user approval)
• Will auto-fixes all categories
• No will-feedback.md generated
• No Will-Jenny loop
• Direct to Tom output

Session State Schema

{
  "session_id": "timestamp",
  "started_at": "ISO-datetime",
  "current_stage": "init|sam_complete|jenny_complete|jenny_approved|will_complete|complete",
  "fast_mode": false,
  "versions": {
    "jenny_draft": {
      "approved": "jenny-draft-approved.md",
      "approved_hash": "SHA256",
      "current": "jenny-draft-revised.md"
    }
  },
  "will_jenny_loop": {
    "max_iterations": 3,
    "current_iteration": 0,
    "user_decisions": []
  }
}

Temporary File Convention

Structural Consistency Validation

Before accepting Jenny revision:

1. Compare agent count (must match approved)
2. Compare skill count (must match approved)
3. Compare workflow type (must match approved)

If violations found: Alert user with diff, request approval for structural changes.

Subagent Skills Reference