HITL Approval Skill

ROOT AGENT ONLY - Uses AskUserQuestion, runs only from root agent.

Purpose: Present plan/summary to user and get explicit approval before proceeding Trigger: Decision point requiring human validation Inputs: summary, affectedFiles, approach Outputs: approved (boolean), feedback (string)

Purpose & Use Cases

Use this skill as a generic approval gate for any major decision:

After /build analysis → Approve implementation approach
After /audit findings → Approve remediation plan
After /architect design → Approve technical direction
After /debug investigation → Approve fix strategy

When Approval Auto-Approves

Approval auto-approves (requires no user intervention) if ANY condition is met:

Condition	Auto-Approve?
Prompt contains "do without approval"	Yes
Prompt contains "just do it"	Yes
Otherwise	Requires approval

Workflow

Step 1: Check Auto-Approve Conditions

IF prompt contains "do without approval" OR "just do it":
    RETURN { approved: true, feedback: null }

CONTINUE to Step 2

Step 2: Present Summary to User

Format the summary clearly with sections:

APPROVAL NEEDED
════════════════════════════════════════

📋 Summary:
{summary text}

📁 Affected Files:
{list of files}

🛠️  Approach:
{approach description}

Ready to proceed?

Step 3: Ask for Approval

Use AskUserQuestion tool with two options:

APPROVE → Continue to next phase
REVISE → Collect feedback → Return to caller

Step 4: Handle Response

If APPROVED:

{
  "approved": true,
  "feedback": null
}

If APPROVED WITH REVISIONS:

{
  "approved": false,
  "feedback": "User requested changes to approach - needs optimization for database queries"
}

Step 5: Return Control to Caller

Return control to calling agent with:

approved: true|false
feedback: string (user's requested changes, if revisions needed)

Calling agent proceeds with:

Execute (if approved)
Revise based on feedback and re-submit for approval
Loop back to investigation phase with updated approach

HITL Tool Enforcement

HITL gates MUST use AskUserQuestion tool. Prose questions are rejected.

Correct HITL:

Use AskUserQuestion tool with:
- question: "Approve PRD package for implementation?"
- options: ["Approve", "Request Changes"]

Incorrect HITL (REJECTED):

"Ready to proceed? Let me know if you'd like any changes."

Why: Prose questions allow agents to continue without explicit user consent. The AskUserQuestion tool creates a blocking gate that ensures user acknowledgment before proceeding.

Detection: Commands check for AskUserQuestion tool call in agent response. Prose-only responses trigger loop back with instruction to use tool.

Input Schema

{
  "summary": "string (2-5 sentences describing what will happen)",
  "affectedFiles": "string[] (list of file paths or patterns)",
  "approach": "string (3-5 sentences explaining HOW it will be done)"
}

Output Schema

{
  "approved": "boolean",
  "feedback": "string | null (only if approved=false)"
}

Examples

Example 1: Change (Requires Approval)

Inputs:
{
  "summary": "Refactor database schema to support multi-tenancy. Affects 12 tables, requires data migration.",
  "affectedFiles": [
    "src/db/schema.ts",
    "src/migrations/",
    "src/services/user.service.ts",
    "src/services/team.service.ts"
  ],
  "approach": "1. Create new schema with tenant_id column. 2. Write migration script. 3. Deploy with blue-green strategy."
}

Processing:
  - Show approval request to user

User sees:
────────────────────────────────────────
APPROVAL NEEDED
════════════════════════════════════════

📋 Summary:
Refactor database schema to support multi-tenancy. Affects 12 tables, requires data migration.

📁 Affected Files:
- src/db/schema.ts
- src/migrations/
- src/services/user.service.ts
- src/services/team.service.ts

🛠️  Approach:
1. Create new schema with tenant_id column.
2. Write migration script.
3. Deploy with blue-green strategy.

Ready to proceed?

User clicks: YES

Output:
{
  "approved": true,
  "feedback": null
}

Example 2: Approval Denied with Feedback

User clicks: NO, requesting changes

Follow-up prompt appears:
"What changes would you like? Be specific."

User responds:
"Don't deploy with blue-green yet. Need to test with read-only mode first."

Output:
{
  "approved": false,
  "feedback": "Don't deploy with blue-green yet. Need to test with read-only mode first."
}

Integration

Called by: /audit, /build, /architect, /debug commands Calls: AskUserQuestion tool Returns: approved (boolean), feedback (string or null) Previous phase: Analysis/investigation/design complete Next phase: Execution (if approved) or revision (if rejected)

Notes

Always honor explicit user instructions in the original prompt about approval
AskUserQuestion is required for this skill (runs in root agent context only)

hitl-approval