docs: add CHANGELOG, ADRs, bump versions to v0.1.41

Version badges and plugin manifests were stale (0.1.29–0.1.33).
Added CHANGELOG.md from git history, created 3 foundational ADRs
(file-based state, three-layer quality, Rust binary), updated
skill/command counts, and removed empty TODOS.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Structured plan-first development plugin for Claude Code with .flow/ task tracking, Agent Teams, and Ralph autonomous mode",
-    "version": "0.1.29"
+    "version": "0.1.41"
   },
   "plugins": [
     {
       "name": "flow-code",
-      "description": "Zero-dependency planning + execution with .flow/ task tracking. Three-layer quality (guard + RP plan-review + Codex adversarial). Full-auto, zero questions. Teams auto-parallel, DAG mutation, Codex-driven decisions, auto draft-PR, session summary. 5 prompt templates. 20 subagents, 25+ CLI commands, 23 skills.",
-      "version": "0.1.29",
+      "description": "Zero-dependency planning + execution with .flow/ task tracking. Three-layer quality (guard + RP plan-review + Codex adversarial). Full-auto, zero questions. Teams auto-parallel, DAG mutation, Codex-driven decisions, auto draft-PR, session summary. 5 prompt templates. 24 subagents, 22 commands, 74 skills.",
+      "version": "0.1.41",
       "source": "./",
       "category": "workflow",
       "tags": [
@@ -26,5 +26,5 @@
       "strict": true
     }
   ],
-  "version": "0.1.29"
+  "version": "0.1.41"
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "flow-code",
-  "version": "0.1.33",
-  "description": "Zero-dependency planning + execution with .flow/ task tracking and Ralph autonomous mode (multi-model review gates). Worker subagent per task with git worktree isolation for parallel execution. Three-layer quality system (guard + RP plan-review + Codex adversarial). Full-auto by default — AI decides from context, zero questions. Teams-default with file locking, DAG mutation, Codex-driven conflict resolution, auto draft-PR. Auto-detected stack profiles with one-command guard (test/lint/typecheck). Enhanced agent definitions with permissionMode/maxTurns/effort. Lifecycle hooks with state preservation (PreCompact injects .flow state into compaction, TaskCompleted auto-unlocks files, SubagentStart context injection). Memory v2 with atomic entries, dedup, and progressive disclosure. TDD enforcement mode. Multi-epic queue with dependency visualization. Includes 20 subagents, 25+ commands, 23 skills.",
+  "version": "0.1.41",
+  "description": "Zero-dependency planning + execution with .flow/ task tracking and Ralph autonomous mode (multi-model review gates). Worker subagent per task with git worktree isolation for parallel execution. Three-layer quality system (guard + RP plan-review + Codex adversarial). Full-auto by default — AI decides from context, zero questions. Teams-default with file locking, DAG mutation, Codex-driven conflict resolution, auto draft-PR. Auto-detected stack profiles with one-command guard (test/lint/typecheck). Enhanced agent definitions with permissionMode/maxTurns/effort. Lifecycle hooks with state preservation (PreCompact injects .flow state into compaction, TaskCompleted auto-unlocks files, SubagentStart context injection). Memory v2 with atomic entries, dedup, and progressive disclosure. TDD enforcement mode. Multi-epic queue with dependency visualization. Includes 24 subagents, 22 commands, 74 skills.",
   "author": {
     "name": "z23cc",
     "url": "https://github.com/z23cc"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-code",
-  "version": "0.1.31",
+  "version": "0.1.41",
   "description": "Zero-dependency planning + execution with .flow/ task tracking and Ralph autonomous mode (multi-model review gates). Worker subagent per task with git worktree isolation for parallel execution. Three-layer quality system (guard + RP plan-review + Codex adversarial). Full-auto by default. Teams-default with file locking, DAG mutation, Codex-driven conflict resolution, auto draft-PR.",
   "author": {
     "name": "z23cc",
@@ -21,7 +21,7 @@
   "interface": {
     "displayName": "Flow-Code",
     "shortDescription": "Plan-first workflow with subagent execution",
-    "longDescription": "Structured plan-first workflow engine. Tracks epics and tasks in .flow/ directory. Spawns isolated worker subagents per task. Ralph mode enables fully autonomous execution with multi-model review gates. 24 subagents, 25+ commands, 23 skills.",
+    "longDescription": "Structured plan-first workflow engine. Tracks epics and tasks in .flow/ directory. Spawns isolated worker subagents per task. Ralph mode enables fully autonomous execution with multi-model review gates. 24 subagents, 22 commands, 74 skills.",
     "developerName": "z23cc",
     "category": "Productivity",
     "capabilities": [

CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to Flow-Code are documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/). Versions use [Semantic Versioning](https://semver.org/).
+
+## [0.1.41] - 2026-04-08
+
+### Added
+- 12 engineering skills across 4 domains: security, performance, database, observability
+- 5 engineering skills: TDD, incremental development, error handling, state management, caching
+- Frontend UI engineering skill for production-quality interfaces
+- References directory with security, performance, and accessibility checklists
+- Pre-launch checklist and skill discovery guide
+- QA and design-review browser automation skills
+- Multi-perspective autoplan review skill (CEO, eng, design, DX)
+- Template generation system with placeholder resolution
+- Memory auto-inject with levels and tag reference
+- Shared preamble startup sequence template
+- Tier metadata to all skill frontmatter
+- Brainstorm phase and `/flow-code:go` full-autopilot entry point
+
+### Changed
+- Unified CLI arg style: positional for primary entity, flags for filters
+- Improved review-backend defaults and skill docs clarity
+- Wired frontend-ui skill into plan/work pipeline
+- Enforced zero-interaction contract across entire go pipeline
+
+### Fixed
+- Pipeline gaps: GO_MODE, dual-phase clarity, Phase 3 PhaseDef
+- Five quality gaps: domain skills, brainstorm→plan handoff, planSync, investigation, memory
+- Comprehensive quality, consistency, and documentation sweep
+
+## [0.1.31] - 2026-04-08
+
+### Added
+- Event-sourced pipeline-first architecture (`flowctl phase next/done`)
+- Shared preamble startup sequence template
+
+### Changed
+- Consolidated plugin: removed deprecated skills, codex dupes, fixed cross-refs
+- Removed all deprecated skill references from docs
+- Removed libSQL/fastembed — pure file-based state
+- Merged 4 Rust crates into 2 (core + cli)
+
+### Fixed
+- Stale references updated to show flow-code-run as primary entry point
+- Test snapshot wildcards to avoid `.flow/` state dependency
+
+## [0.1.0] - 2026-04-07
+
+### Added
+- Initial fork from gmickel/flow-next v0.26.1
+- Rust `flowctl` binary: task DAG, state machine, file locking, cycle detection
+- PID+TTL hybrid file locking with read/write/directory_add modes
+- Schema migration infrastructure
+- Atomic state writes with rename and error propagation
+- Dual-tier worker timeout and deadlock detection
+- Enhanced circuit breaker with regression, oscillation detection
+- CI pipeline: shellcheck, cargo-audit, JSON validation, shell integration tests
+- RTK hook caching for performance
+
+### Changed
+- Renamed flow-next → flow-code across all dirs, files, and content
+- Flattened phase/step numbering to sequential integers
+- Split monolithic smoke_test.sh into focused test files

README.md

@@ -7,7 +7,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
 [![Claude Code](https://img.shields.io/badge/Claude_Code-Plugin-blueviolet)](https://claude.ai/code)
 
-[![Version](https://img.shields.io/badge/Version-0.1.31-green)](https://github.com/z23cc/flow-code/releases)
+[![Version](https://img.shields.io/badge/Version-0.1.41-green)](https://github.com/z23cc/flow-code/releases)
 
 [![Status](https://img.shields.io/badge/Status-Active_Development-brightgreen)](https://github.com/z23cc/flow-code/releases)
 

README_CN.md

@@ -7,7 +7,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
 [![Claude Code](https://img.shields.io/badge/Claude_Code-Plugin-blueviolet)](https://claude.ai/code)
 
-[![Version](https://img.shields.io/badge/Version-0.1.31-green)](../../CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-0.1.41-green)](../../CHANGELOG.md)
 
 [![Status](https://img.shields.io/badge/Status-Active_Development-brightgreen)](../../CHANGELOG.md)
 

TODOS.md

@@ -19,9 +19,9 @@ Use `docs/decisions/` with sequential numbering:
 
 ```
 docs/decisions/
-  ADR-001-json-file-based-storage.md
-  ADR-002-wave-checkpoint-execution-model.md
-  ADR-003-teams-file-locking-protocol.md
+  ADR-001-pure-file-based-state.md
+  ADR-002-three-layer-quality-gates.md
+  ADR-003-rust-single-binary.md
 ```
 
 Use the template at `references/adr-template.md` as your starting point.

docs/adr-guide.md

@@ -0,0 +1,28 @@
+# ADR-001: Pure File-Based State (No Database)
+
+## Status
+ACCEPTED
+
+## Date
+2026-04-07
+
+## Context
+Flow-Code needs persistent state for task DAGs, pipeline progress, file locks, and review receipts. Early versions used libSQL (embedded SQLite) with fastembed for vector search. This added significant binary size, async runtime complexity, and cross-platform build issues.
+
+The plugin runs as a CLI tool invoked by Claude Code — it doesn't need concurrent connections, complex queries, or full-text search. State access patterns are simple: read-modify-write on small JSON files.
+
+## Decision
+Remove libSQL and fastembed entirely. Use plain JSON/JSONL files in `.flow/` for all state, with advisory file locks (`fs2`) for concurrency safety and atomic rename for crash safety.
+
+## Alternatives Considered
+
+| Option | Pros | Cons | Why not? |
+|--------|------|------|----------|
+| libSQL (SQLite) | Familiar SQL, ACID | Binary bloat (~15MB), async runtime, cross-compile pain | Overkill for simple key-value state |
+| JSON files (chosen) | Zero deps, readable by any tool, trivial debugging | No complex queries | Queries not needed — state is small |
+| RocksDB | Fast, embedded | C++ dependency, cross-compile, opaque format | Even more bloat than SQLite |
+
+## Consequences
+- **Easier:** Single binary with no native deps, state inspectable via `cat`/`jq`, simpler CI
+- **Harder:** No SQL queries — must load full file to filter (acceptable given file sizes < 100KB)
+- **Risk:** File locking is advisory-only — malicious or buggy tools could corrupt state. Mitigated by atomic rename writes.

docs/decisions/ADR-001-pure-file-based-state.md

@@ -0,0 +1,30 @@
+# ADR-002: Three-Layer Quality Gate System
+
+## Status
+ACCEPTED
+
+## Date
+2026-04-08
+
+## Context
+A single review pass (lint or AI review) catches some issues but misses entire categories. Lint catches syntax but not spec drift. AI review catches design issues but has blind spots from the same model that wrote the code. We needed independent, complementary layers.
+
+## Decision
+Implement three non-overlapping review layers that every epic passes through:
+
+1. **Guard** (`flowctl guard`) — Deterministic: lint, type-check, test. Runs at worker Phase 6, wave checkpoint, and close.
+2. **RP Plan-Review** — Code-aware spec validation via RepoPrompt context_builder. Catches spec-code misalignment.
+3. **Codex Adversarial** (`flowctl codex adversarial`) — Cross-model (GPT) adversarial review. Different model family catches blind spots Claude might share.
+
+## Alternatives Considered
+
+| Option | Pros | Cons | Why not? |
+|--------|------|------|----------|
+| Single AI review | Simple | Same model, same blind spots | Insufficient coverage |
+| Lint + one AI review | Better | Still same-model bias | Missing adversarial perspective |
+| Three layers (chosen) | Complementary coverage, cross-model | Slower, requires Codex API | Worth it for quality |
+
+## Consequences
+- **Easier:** High confidence in shipped code, catches issues at the right layer
+- **Harder:** Pipeline takes longer, requires both RP and Codex backends configured
+- **Risk:** Review fatigue from false positives. Mitigated by circuit breaker (max 2-3 iterations per layer)