v0.1.5 — alpha.1 —— User-Centered Workflow Preview

What's new

• Added codoop-ux-walkthrough, a standalone skill for reviewing completed, user-visible work from a persona's perspective.
• Loop 3 can now optionally generate an advisory experience_report.md after technical verification.
• Experience walkthroughs are non-blocking: they do not change code, block delivery, or automatically create follow-up tickets.
• Ticket creation now asks in plain language whether UI screenshot verification should be enabled for user-facing changes.

Improvements

• Clarification questions in codoop-ticket now use clearer, outcome-focused language while keeping specifications precise.
• Updated English and Chinese documentation, installation guidance, and release metadata.

Alpha notice

This is an alpha release intended for early evaluation. Feedback on the UX walkthrough workflow and report format is especially welcome.

v0.1.4 — Remove files_to_edit; promote now requires human approval

Breaking

• files_to_edit removed entirely. The concept (introduced as a permission
  whitelist, downgraded to an advisory hint in 0.1.2) is gone from the whole
  pipeline:

  • the Ticket model no longer carries the field
  • ticket init no longer scaffolds it
  • the spec.md template drops its "Editable Files" section
  • update-metadata no longer infers it (and actively strips a stale field
    from older tickets)
  • pick / takeover JSON output no longer includes it

  Edit-scope guidance now lives solely in spec.md prose — the agent stays
  within the scope the spec describes.

  Migration: none required. Old tickets that still contain the field keep
  working — unknown metadata fields are ignored, and the next update-metadata
  run cleans the field up automatically.

Added

• Promote requires explicit user approval. codoop-ticket's Finalize stage
  now mandates showing the ticket summary (id / title / modules) and getting
  user confirmation before ticket promote, and forbids --force without
  prior approval. pending/ is the Loop 3 pickup queue — an unreviewed promote
  means an agent may start building from an unapproved design.

Fixed

• README links to the removed LOOP3_EXECUTION_GUIDE.md now point to
  docs/loop-3-agent-centric.md
• Stale skills/codoop-flow/scripts/ CLI paths updated to the actual
  codoop-ticket / codoop-execute script locations
• Removed discover --agent CLI examples replaced with the in-session
  /skill codoop-discover invocation

Full Changelog: v0.1.3...v0.1.4

v0.1.3 — Ticket runner lease

What's new

Fixes concurrent worktree writes. Two runners could previously resume the same in_progress ticket and clobber each
other's work. Now each ticket gets a lease when picked — a runner without the token is turned away
(blocked_by_active_runner) and the worktree is left untouched.

• takeover <ticket_id> — hand a stuck ticket to a fresh runner (leases never expire; liveness is your call).
• status now shows how far each in-progress ticket got: held_by, todo (e.g. 3/8), worktree_dirty,
  dev_commits.
• Fixed a double-pick race — two concurrent first-picks can no longer both claim the same pending ticket.

Fully back-compatible: existing tickets and automations keep working (--lease is optional on verify/finish/fail).

Full changelog: see CHANGELOG.md

v0.1.2 — Ticket types (feature/fix) & advisory edit scope

Highlights

✨ Ticket types: feature & fix

Tickets now carry an optional ticket_type in metadata.json (default
feature), so the design flow fits the work:

• feature — the full flow: module_prd.md + spec.md required.
• fix — a lightweight flow: skips PRD/Spec and captures the defect in
  bug_report.md (Symptom / Reproduction / Root Cause / Expected Behavior /
  Scope). No more inventing a PRD and spec just to file a small bug fix.

plan.md + todo.md remain recommended for both types. codoop-ticket ticket init gains --type feature|fix; the codoop-ticket skill infers the type
from
your request but always confirms before scaffolding. Loop 3 derives the
fallback
commit prefix from the type (feat / fix).

🔧 files_to_edit is now advisory, not an enforced gate

Loop 3 verify no longer fails a ticket for edits outside the files_to_edit
whitelist. Edit scope (from spec.md / metadata.json) is now guidance the
agent reads — not a hard gate — which unblocks tickets that legitimately need
to
touch adjacent files. verify keeps two hard gates: tests pass, and (for
ui_capture tickets) UI screenshots. files_to_edit is now an optional
field.

Upgrade notes

• Fully back-compatible. Existing tickets without ticket_type behave
  exactly as before (treated as feature).
• Behavior change: if you relied on verify blocking out-of-scope edits,
  that gate is gone. Scope is now advisory guidance for the agent.

Full changelog:
v0.1.1...v0.1.2

v0.1.1 — Documentation Overhaul & Loop 3 Deep Dive

Overview

Comprehensive documentation update clarifying the three-loop AI-driven development system. This release focuses on Loop 3's local-first workflow, deterministic guardrails, and provides complete guides for all three loops.

🎯 What's New

Documentation

LOOP3_EXECUTION_GUIDE.md - Comprehensive deep-dive (5000+ words)

• Complete 7-step workflow breakdown: Pick → Build → Verify → Review → Merge → Finish
• Worktree architecture and git lifecycle
• Three hard verification gates: edit-scope whitelist, tests, UI screenshots
• Python script execution logic for all CLI commands (pick, verify, finish, fail, status)
• Self-healing mechanism with budget tracking
• Local repository workflow with explicit user control over merges
• Edge case handling and idempotency guarantees
• Architecture diagram showing component relationships

README.md - Complete restructuring

• Clear positioning: "three-loop AI-driven development system"
• Loop 1 (Venture-Discovery): Product design → docs/backlog/
• Loop 2 (Human-Centric): Ticket design → docs/tickets/pending/
• Loop 3 (Agent-Centric): Code execution → main branch
• Loop-specific Quick Start sections for each workflow
• Dual modes: continuous /loop processing and single-ticket manual mode
• Design philosophy: "thinking to agent, counting to script"
• Reorganized FAQ: 15+ comprehensive questions in 4 categories
• Key properties table: local-first, idempotent, deterministic, transparent

README.zh-CN.md - Full synchronization

• Complete translation of all English updates
• Culturally appropriate Chinese phrasing
• Consistent terminology across both versions

Workflow Clarifications

Local-first design

• User controls merge timing, not remote push
• Agent asks: "Merge dev/<ticket_id> to main?" and waits for user decision
• All changes stay local until explicit approval

Idempotent execution

• /loop command safely repeatable without risk of double-processing
• Automatic resume of in-progress tickets on repeated calls
• Supports Agent restarts and long-running executions

Async-friendly scheduling

• Timing controlled by Agent's /loop scheduler, not Python internals
• Works with Claude Code, Codex, or any Agent with loop/scheduler capability

Clarifications on data safety

• Worktree deletion explained: only filesystem temp files deleted, commits permanent in .git
• Edit-scope verification: cannot be bypassed by AI hallucination
• Three hard gates: unhackable deterministic checks

✅ Backward Compatibility

100% compatible - No breaking changes

• CLI interface unchanged: pick, verify, finish, fail, status all work identically
• metadata.json format remains compatible
• codoop_flow.toml configuration unchanged
• Ticket directory structure unchanged
• Existing installations continue to work as-is without modification

📦 Migration for Existing Users

Claude Code / Codex Plugin Users

Plugins auto-sync from marketplace (may take 5-30 minutes)
Restart IDE to get latest version
No manual action required

Local Development (git clone)

git pull origin main
# That's it! No reinstall needed.

Manual Installation

cp -R skills/codoop-execute ~/.codex/skills/

📊 Key Improvements

Aspect	Before	After
Project positioning	Unclear	"Three-loop AI-driven system"
Loop 3 documentation	1 sentence	5000+ word comprehensive guide
Workflow clarity	Agent controls merge	User controls merge
FAQ coverage	4 basic questions	15+ comprehensive questions
Chinese docs	Outdated	Fully synchronized
Guardrails explanation	Implicit	Explicitly documented

📚 Resources

• CHANGELOG.md — Detailed version history
• LOOP3_EXECUTION_GUIDE.md — Complete Loop 3 mechanics
• README.md — Project overview and quick start
• README.zh-CN.md — Chinese version (中文)
• docs/engineering-design.md — Three-loop blueprint

📍 Release Info

• Release Date: 2026-07-07
• Commits: ecd0dd2..b811430
• Status: Stable, production-ready
• Breaking Changes: None

---

Thank you for using codoop-flow!

Questions? Check the FAQ section in README or open an issue.