loop-coding

Orchestrator for large coding tasks. I (Silvana/Opus) coordinate; subagents and scripts do the heavy lifting.

Core principles

1. Scripts-first. If a step can be formalized as a shell/python script, it MUST be a script, not an AI call. Scripts are cheaper, faster, deterministic, and free from token drift. AI is reserved for: generating prompts for subagents, reading merged artifacts, making judgment calls, writing actual code, critiquing code.
2. Codex for critique, Opus for code, double only on Review. Research is dual (Sonar+Sonnet, parallel). Audit and Plan are Codex GPT-5.5 ONLY — Opus is NOT spawned for these phases (Codex is the stronger critic + architect, and Opus subscription is the scarce resource we protect). Implement is Opus (best in our stack). Review is the only dual-model phase: Codex + Opus in parallel, scripts merge outputs and flag divergence as risk. Rationale: Audit/Plan = single critic is enough when the critic is GPT-5.5; Review = code already exists, two pairs of eyes catch different bugs, worth the Opus token.
3. Respect existing code. Before building new, audit what already exists: our repos (your-repos), code in ~/.claude/, instructions in CLAUDE.md / rules.md / SOUL.md. Do NOT reinvent if a solution already exists.
4. Auto-generate helper skills when needed. After audit, if a gap is detected that would repeat 3+ times and has no existing solution, invoke the global skill-creator at ~/.claude/skills/skill-creator/ via an Opus subagent with a pre-answered non-interactive brief (otherwise skill-creator's interview phase stalls). Validate every generated sub-skill with quick_validate.py before use. run_eval.py for trigger evaluation works on Max OAuth; run_loop.py description optimization requires ANTHROPIC_API_KEY and is blocked in this workspace. Full workflow + path conventions: references/sub-skill-generation.md.
5. Rent external skills safely. Skills from skills.sh can be downloaded into rented-skills/{task-id}/ for the duration of the task, but ONLY after passing security scan (scripts/skill-security-scan.sh).
6. Max 3 fix iterations. If review-fix loop does not converge in 3 iterations, escalate to prince with remaining issues.
7. Staging-first deploy. If project has deploy.sh: staging is autonomous, production requires prince explicit "да, на prod". Push to git is autonomous.

When to use

Trigger on: миграция, переезд, крупный рефакторинг, большая фича, переделать систему, loop-coding, лупкодинг, полная переработка.

Do NOT trigger on: single bug fixes, typo corrections, 1-file edits, planning-only discussions, documentation updates.

Sibling skill — fast-loop-coding (~/.claude/skills/fast-loop-coding/SKILL.md): for tasks 50-300 LOC, 1-3 files, single subsystem, 15-30 min. 4 phases instead of 7, no parallel research, no double review, 1 fix iteration. Use it when task fits its decision tree; escape to this skill mid-task if scope grows past 300 LOC / 3 files / multi-subsystem.

Workflow

Seven phases, strict order:

1. Research    (Sonar + Sonnet + GitHub-scout + skill-scout, parallel)
2. Audit       (Codex GPT-5.5 ONLY; respect existing code)
3. Plan        (Codex GPT-5.5 ONLY — arch + impl + test skeletons brief)
4. Implement   (Opus coder subagents; run tests after each commit)
5. Review      (Codex + Opus parallel; extend tests)  ← only dual-model phase
6. Fix-loop    (max 3 iterations; else escalate)
7. Ship        (git push auto; staging auto; prod requires prince OK)

Each phase produces an artifact in the run directory and updates the milestone bar.

Run directory

Every invocation creates a dedicated directory:

~/.claude/loop-coding-runs/{YYYY-MM-DD}-{task-slug}/
├── RESEARCH.md       (phase 1 output)
├── AUDIT.md          (phase 2 output)
├── PLAN.md           (phase 3 output)
├── REVIEW.md         (phase 5/6 output; severity-sorted)
├── FIX-LOG.md        (iteration log)
├── DEPLOY.md         (phase 7 log)
├── tests/            (TDD skeletons from Plan phase)
└── rented-skills/    (external skills used during this task)

Artifacts persist after task completion for audit trail. Archived to runs/archive/ by a monthly cron.

Phase execution

For each phase, read the corresponding reference file for detailed instructions:

• Phase 1 Research -> references/phase-1-research.md
• Phase 2 Audit -> references/phase-2-audit.md
• Phase 3 Plan -> references/phase-3-plan.md
• Phase 4 Implement -> references/phase-4-implement.md
• Phase 5 Review -> references/phase-5-review.md
• Phase 6 Fix-loop -> references/phase-6-fix-loop.md
• Phase 7 Ship -> references/phase-7-ship.md

Cross-cutting concerns:

• GitHub scouting -> references/github-scout.md (min 2000 stars, prefer 10k+)
• skills.sh scouting + rent flow -> references/skill-scout.md
• Security scan for external skills -> references/skill-security.md
• Test strategy per language -> references/test-strategy.md
• Auto-generation of sub-skills -> references/sub-skill-generation.md

Scripts (automation backbone)

Every formalizable step has a script. Invoke them, do not reimplement:

Scripts are self-documenting (pass -h for usage).

Model allocation

Codex is never used for research (too slow, too expensive) or for code writing (Opus is stronger in our stack). Codex is strictly critic/architect, and is now the SOLE model for Audit and Plan to offload Opus subscription. Opus only enters during Implement, test-skeleton writing under Codex plan, fix-loop, and Review.

Milestone display

After every phase transition, render and send the bar to prince. Seven segments, one per phase. See scripts/milestone-render.sh.

▰▱▱▱▱▱▱ 14% · Research
▰▰▱▱▱▱▱ 28% · Audit
▰▰▰▱▱▱▱ 42% · Plan
▰▰▰▰▱▱▱ 57% · Implement
▰▰▰▰▰▱▱ 71% · Review
▰▰▰▰▰▰▱ 85% · Fix-loop
▰▰▰▰▰▰▰ 100% · Ship

Escalation

Hard stops where the loop cannot proceed autonomously:

1. After 3 fix-loop iterations with remaining critical/high issues -> Telegram to prince with REVIEW.md + FIX-LOG.md attached.
2. Before production deploy (always) -> explicit prince approval required.
3. If research finds no viable approach and no patterns exist -> ask prince for direction.
4. If a rented skill fails security scan AND no alternative exists -> report to prince, do not use skill.

Use scripts/escalate.sh - it sends the right files with the right caption.

Starting a run

RUN_DIR=$(bash scripts/init-run.sh "cognee-migration")
bash scripts/phase-1-research.sh "$RUN_DIR" "migrate to Cognee graph RAG"
bash scripts/parallel-review.sh audit "$RUN_DIR"

Orchestration is primarily shell-driven; I step in for judgment calls between phases and to spawn subagents for code-writing tasks.

Versioning

Current: v1.0 (2026-04-17).

Skill evolves via iteration after real use. Feedback from each run goes into ~/.claude/skills/LEARNINGS.md and promotes into this SKILL.md when score >= 0.8.