Skip to content

feat: Phase 1 scaffold — hooks, skills, agents, rules, templates#1

Open
robotlearning123 wants to merge 28 commits intomainfrom
feat/phase1-scaffold
Open

feat: Phase 1 scaffold — hooks, skills, agents, rules, templates#1
robotlearning123 wants to merge 28 commits intomainfrom
feat/phase1-scaffold

Conversation

@robotlearning123
Copy link
Copy Markdown
Member

@robotlearning123 robotlearning123 commented Mar 28, 2026

Summary

Complete v0.0.1 scaffold for agent-driven development with Claude Code + Codex.

This PR delivers the full Phase 1 scaffold, shaped by ccz deep review (6.4/10 → estimated 7.5-8.0):

  • 9 hooks — observability, quality gates, branch guards, context rotation, lint, stall detection
  • 5 skills — /init-project, /dispatch, /plan, /ship, /metrics
  • 4 agents — coordinator, implementer, reviewer, tester
  • 4 rules — context management, git workflow, quality standards, security
  • 3 templates — CLAUDE.md per stack (Python, React, fullstack) + AGENTS.md
  • Test suite — 10/10 passing (tests/test_hooks.sh)
  • Research — 5 reports informing the design

Bug fixes (from ccz review)

  • Float comparison crash in context rotation hook (bash [ -ge ] on decimals)
  • set -euo pipefail causing premature exits on expected grep/jq failures → set -uo pipefail
  • pytest exit code 5 (no tests collected) treated as failure in 3 hooks
  • npm test exit code lost through pipe in subagent-stop-metrics
  • Stall detector dead code (not wired in settings.json)

Shell conventions (unified across all hooks)

  • set -uo pipefail (NOT -euo)
  • # Requires: header declaring external deps
  • # shellcheck shell=sh for static analysis
  • Explicit error handling via || true, 2>/dev/null

Test plan

  • tests/test_hooks.sh — 10/10 passing
  • Installed on lab-manager (real project validation) — all hooks adapted and working
  • find .claude/hooks -name "*.sh" -exec test -x {} \; -print — all executable

Generated with Claude Code
via Happy

Co-Authored-By: Claude noreply@anthropic.com
Co-Authored-By: Happy yesreply@happy.engineering

sandia777 and others added 28 commits March 27, 2026 16:40
@sandia777 @claude
feat(scaffold): initial agent-driven scaffold
6fbc552 
Agents: coordinator, implementer, reviewer, tester
Hooks: post-edit-lint, branch-guard, stall-detector, subagent-stop-verify, task-completed-gate
Rules: context-management, git-workflow, quality-standards, security
Observability: metrics and traces directories
Docs: DESIGN.md spec + research docs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@sandia777 @claude
feat(hooks): full observability hooks with metrics and traces
d47b5ac 
- post-tool-use-trace: JSON-lines action logging per session
- subagent-stop-metrics: outcome logging + test verification
- pre-compact-rotation: 65% context rotation enforcement
- session-start-handover: auto episodic memory generation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@sandia777 @claude
feat(scaffold): complete v0.0.1 scaffold structure
d81a168 
- README with quick start and Day 1 scenario
- CLAUDE.md for the repo itself (<40 lines)
- settings.json wiring all 9 hooks to 6 lifecycle events
- /init-project skill with stack detection
- CLAUDE.md templates (Python, TypeScript)
- AGENTS.md template
- Structured docs (WORKFLOW, PROGRESS, PLAN, PROMPT, CONVENTIONS)
- Procedural memory example (python-fastapi-feature)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
feat(docs): context management protocol + structured memory
d00ad07 
4-file doc pattern: PROMPT.md, PLAN.md, PROGRESS.md, CONVENTIONS.md
Structured memory: procedural/python-fastapi-feature.md,
pitfalls/common-agent-failures.md, episodic/ (empty, gitkeep)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@sandia777 @claude
feat(skills): add /dispatch skill + VERSION + LICENSE
722eab5 
- /dispatch skill: wave planning, dependency resolution, parallel execution,
  cross-engine review, staged merging protocol
- VERSION: 0.0.1
- LICENSE: MIT

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(scaffold): rename misleading hook, reduce trace noise, add .gitig…
74fe5a1 
…nore

- Rename session-start-handover.sh → session-end-episodic.sh (matches purpose)
- Reduce trace hook scope: Bash|Edit|Write only (Read/Glob/Grep too noisy)
- Add .gitignore (metrics, traces, episodic are runtime data)
- Add fullstack + react templates (from ralph loop)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
feat(skills): /init-project skill + CLAUDE.md/AGENTS.md templates
6140f26 
/init-project: stack detection, config generation, agent-readiness scoring
Templates: python, react, fullstack CLAUDE.md + AGENTS.md
Auto-detects: test/lint/format commands, framework, project type

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@sandia777 @claude
feat(scaffold): wire hooks in settings.json + /init-project skill + t…
f8cc47d 
…emplates

settings.json: PreToolUse, PostToolUse, SubagentStop, Stop, PreCompact, TaskCompleted
init-project skill: stack detection, config gen, readiness scoring
Templates: python, react, fullstack CLAUDE.md + AGENTS.md
README: cleaned up

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@sandia777 @claude
fix(hooks): reference correct Stop hook filename
9d6d9e1 
settings.json referenced non-existent session-start-handover.sh but the
actual file is session-end-episodic.sh.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(skills): remove duplicate init-project.md skill file
ecef3df 
Keep .claude/skills/init-project/SKILL.md (directory format, CC standard)
and delete the root-level .claude/skills/init-project.md duplicate.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(hooks): align context rotation thresholds to spec (65%/55%)
980630e 
Spec says 65% mandatory rotation, hook enforced at 70%. Changed to
65% mandatory and 55% warning (10% before mandatory).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(hooks): fix malformed YAML from grep -c fallback in episodic hook
540beb6 
grep -c outputs "0" on no match but exits 1, causing || echo "0" to
append a second "0" line. Use || VARIABLE=0 pattern instead.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(hooks): capture npm test exit code properly in subagent-stop-metrics
c1d6899 
|| true after command substitution makes $? always 0. Capture output
first, then check $RC separately.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(hooks): implement actual quality gate in task-completed-gate
f0a6e01 
Was a stub that only logged. Now checks tests and lint before allowing
task completion. Exit 2 blocks completion if checks fail.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(hooks): add strict mode to 4 hooks missing set -euo pipefail
f326af5 
post-edit-lint.sh and stall-detector.sh use set -uo pipefail (no -e,
non-blocking). pre-tool-branch-guard.sh and subagent-stop-verify.sh
use set -euo pipefail (blocking hooks).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(hooks): detect default branch instead of hardcoding main
2f5aed2 
Use git symbolic-ref to detect origin's default branch (main or master)
with fallback to main. Fixes hooks failing on repos using master.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(templates): remove duplicate agents-md.md template
58509c1 
Keep AGENTS.md.template as the canonical template, remove agents-md.md
duplicate.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(templates): remove duplicate CLAUDE.md.{stack} template variants
e230010 
Keep claude-md-{stack}.md naming convention (claude-md-python.md,
claude-md-react.md, claude-md-fullstack.md). Remove CLAUDE.md.python
and CLAUDE.md.typescript duplicates.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(docs): correct hook count in README from 8 to 9
786aa2d 
There are 9 hook scripts, not 8.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(config): add settings.local.json and *.log to .gitignore
59bfd9c 
Prevent local settings overrides and log files from being committed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(docs): correct hook name in PROGRESS.md
b831531 
Referenced session-start-handover but the actual hook is
session-end-episodic.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(hooks): capture npm test exit code before piping through tail
fd3ee9a 
Both subagent-stop-metrics.sh and subagent-stop-verify.sh had the same
bug: `RC=$?` after `$(npm test 2>&1 | tail -1)` captures tail's exit
code (always 0), not npm test's exit code. Fixed by running npm test
first, capturing RC, then tailing output separately.

Found by: QA review round 2 (12/13 pass, this was the 1 fail + 1 new)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude
fix(hooks): use set -uo (not -euo) in branch-guard for jq graceful fa…
f6182f4 
…ilure

jq exits non-zero on malformed input. With set -e, the entire hook
crashes (exit 127) instead of gracefully exiting 0. Changed to set -uo
and added 2>/dev/null || echo "" fallback on jq call.

Found by: strict QA real test suite (3 failures, this was 1 of them).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@sandia777 @claude @happy-otter
fix(hooks): fix 5 bugs found by ccz review (6.4/10 → target 8+)
6b3487d 
- pre-compact-rotation.sh: handle float context percentages (bash -ge
  only accepts integers, 72.5 would crash)
- subagent-stop-verify.sh: handle no-remote repos (fallback to local
  main/master/current), handle pytest exit 5 (no tests collected)
- subagent-stop-metrics.sh: same no-remote + pytest fixes, fix test
  detection glob (*/test → **/test), add Go func Test pattern
- task-completed-gate.sh: handle pytest exit 5
- settings.json: wire stall-detector.sh (was dead code)
- Add test suite: 10 tests, all passing

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
@sandia777
docs(design): add methodology notes, fix unverified claims
25b3b7c 
- Add methodology note to header: star counts are estimates from
  public npm data, see docs/research/ for details
- Replace exact star counts (118K★, 52K★) with estimated installs
  (npm, est.) to signal uncertainty
- Fix cc-manager success rate claim: now references docs/research/
  for methodology instead of stating as fact
- Soften compound failure claim from "85% per-step = 20% over 10"
  to "Est. 85% per-step = 20% over 10 steps (compound)"
- Context degradation: note 65% is a chosen threshold, not a
  Stanford citation (no specific paper found)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)
@sandia777 @claude @happy-otter
feat(skills): add /plan, /ship and /metrics skill definitions
b5ae56c 
 to agent-driven scaffold

to Plan: feature spec review with 3 parallel reviewers (security, architecture, correctness)
to Ship: quality pipeline (tests, lint, review) to PR
to Metrics: summary, session, trends, failures, clean subcommands

Coloses ccz review gap: missing /plan, /ship, /metrics skills (P1)

README referenced all 3 but now implemented

All integrate into workflow after /init-project

Generated with [Claude Code](https://claude.com/claude-code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
@sandia777
style(hooks): unify shell style, add dependency declarations
5625713 
- Standardize all hooks to set -uo pipefail (not -euo)
  - -euo causes premature exit on grep/jq failures
  - All hooks handle errors explicitly via || true / 2>/dev/null
- Add Requires: header to all hooks listing external deps
- Add shellcheck shell=sh directive to all hooks
- Update CONVENTIONS.md with full dependency table
- Update CLAUDE.md to reflect -uo (not -euo) convention
- Update post-edit-lint.sh to use command -v for graceful dep check

All 10 tests pass.

Closes: ccz review gap - inconsistent shell style (P3)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

Generated with [Claude Code](https://claude.com/claude-code)
via [Happy](https://happy.engineering)
@sandia777 @claude @happy-otter
chore: bump version to 0.0.2
ad97cb7 
Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@robotlearning123 @sandia777