pdlc-autopilot: Instructions file for Claude Code

CLAUDE.md — PDLC Autopilot

Project Overview

PDLC Autopilot is a CLI skill for Claude Code that orchestrates autonomous product development lifecycles using a Director/Actor/Critic pattern.

Code Conventions

Shell Scripts (hooks/)

• All hook scripts MUST exit 0, even on error. Use trap 'exit 0' ERR (or trap '...; exit 0' ERR if output is needed).
• Use set -eo pipefail at the top of hook scripts that have ERR traps (-u / nounset bypasses the ERR trap and breaks fail-open). Use set -euo pipefail in library scripts without ERR traps.
• Use local only inside function bodies. Never use local in the main script body or inside loops/conditionals outside functions (macOS bash 3.2 fatal error).
• Atomic writes: write to .tmp then mv to final path. Never write directly to state files.
• HANDOFF.md uses flat YAML frontmatter (no nested objects). Parse with awk, not yq.
• pdlc_get_field / pdlc_set_field in hooks/lib/pdlc-state.sh are the canonical state accessors. Do not reimplement frontmatter parsing inline.
• Use substr($0, length(key)+3) in awk to preserve values containing : . Never use just $2 with -F': ' for value extraction.
• Prefer single-word values in HANDOFF.md fields (e.g., PASS_WARN not PASS WITH WARNINGS) to avoid word-splitting issues.
• Environment variable names: PDLC_ prefix for all configurable vars.

Process Enforcement

• SpecGate (hooks/spec-gate.sh): Blocks spec generation via Task tool. Specs must use Kiro skills.
• CriticGate (hooks/critic-gate.sh): Blocks Actor dispatch without prior critic review.
• Stop Guard (hooks/pdlc-stop-check.sh): Blocks exit when PDLC tasks are incomplete.
• Deny messages use <error-recovery> XML framing for LLM self-correction.
• The "matcher": "Task" in settings.json ensures gate hooks only fire for Task tool calls.
• PDLC_DISABLED=1 bypasses all blocking hooks (SpecGate, CriticGate, Stop Guard, Outer Loop). Used during self-development to avoid bootstrapping circularity. External governance provided by GitHub Spec Kit (.specify/).