louke 0.3.0__tar.gz

louke-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 louke team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

louke-0.3.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: louke
+Version: 0.3.0
+Summary: Lòukè - 超越氛围写意，乃是工笔造物 (beyond vibes, into craft)
+Author: louke team
+License: MIT
+Project-URL: Homepage, https://github.com/zillionare/louke
+Project-URL: Repository, https://github.com/zillionare/louke
+Project-URL: Issues, https://github.com/zillionare/louke/issues
+Keywords: spec-driven,tdd,multi-agent,craft,hold-point,agent-framework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# louke
+
+> **beyond vibes, into Louke(craft).**
+
+![louke pipeline](docs/hero.svg)
+
+[🇨🇳 中文](README.zh.md) · [🇺🇸 English](README.md)
+
+**louke is a multi-agent collaborative development methodology built on spec-first, test-driven, and tool-aligned agent behavior.** Every stage transition is a tool-enforced check.
+
+---
+
+### Why louke?
+
+You can't build a real software with one-sentence vibecoding.
+
+A real software has hundreds to thousands of sub-requirements, tens of thousands of execution paths and boundary checks.
+
+Real work takes concrete, detailed specs, acceptance criteria, and test plans. Humans must participate in and guide the production of these documents; tools must break them into traceable sub-items so agent code maps one-to-one to those items. Only then can we build a retractable, traceable, trustworthy software production process.
+
+That's the value of louke. Beyond vibecoding — agent programming becomes precision manufacturing, executing every detail you specified perfectly.
+
+When vibecoding:
+
+- You haven't figured out what software you want, yet expect the agent to know
+- Words are always suggestive and leave too much room for imagination, but software must be precise
+- You have many Stories, but neither AI nor you has formed a complete blueprint
+
+Even spec-kit / superpowers / oh-my-openagent don't turn spec into a "programming contract". For spec to be a contract, three things must hold simultaneously — and louke is the only one that achieves them:
+
+- **Sub-requirements are orthogonal** — non-conflicting and non-overlapping, already pruned by Occam's razor
+- **Right-sized granularity** — you can't expect an agent to read a 10,000-word document and still grasp every small detail, unless you break them into items that fit cleanly into a PR
+- **Traceable** — every thread from requirement to code to test must be bidirectionally traceable: forward to find the source, backward to find the landing. Any requirement that can't be matched to its code and tests is a blank check hanging on the wall
+
+And the deepest gap between louke and other frameworks: louke turns this into **Infrastructure-as-Checkpoint** — the traceable loop is not in the AI's self-discipline, but in the forced execution of external CLIs at commit-time. `exit 0/1` is an OS process return value; you can't bypass it. The engineering world only recognizes this one language.
+
+### What louke provides
+
+louke turns the contract's three principles into 5 observable things. Each maps to an `lk` command or a traceable artifact — not just prompts, but tools:
+
+- **spec → GitHub issue, commits must reference issue** — Lex converts each FR into an issue; Devon's commit message enforces `#NNN` format. Requirement to code, one-way trace, never lost
+
+- **test ↔ AC-FRXXXX-YY auto-association, CI static validation closes both directions** — every test docstring must carry an `AC-FRXXXX-YY` ID. `lk archer ci-scan` validates at commit-time: every AC must be referenced by a test, every test must reference an AC. If the loop doesn't close, merge is blocked
+
+- **Anti-pattern CI gate + identity consistency check** — `lk keeper gate` statically scans 8 anti-patterns (`assert True` / `try/except: pass` / no-issue skip / mock-framework core / ...). `lk scout identity-check` locks gh/git identity consistency before workflow start. Violations block
+
+- **Project wiki auto-distillation** — based on LLM compounding engineering, `.louke/raw/` (each agent's session records) → `.louke/wiki/` (structured knowledge). Facts, decisions, current state at a glance, lint-checkable
+
+- **Socratic requirement interrogation** — Sage asks multiple rounds of questions around a vague story until it produces traceable `spec.md` + `acceptance.md`
+
+`louke` defines 12 specialized agents, a 10-stage pipeline, and an `lk` CLI — so every transition is a real check, not the soft "agents review each other". Each agent has its own dedicated toolbox; at every hold point, work is gated for verification.
+
+### The Pipeline
+
+| Stage | Implementer | Reviewer | Notes |
+|---|---|---|---|
+| M-FOUND | Scout | Warden | Project setup + permission gate |
+| M-SPEC | Sage | Lex | spec + FR → issue, Lex reviews + 100% verifies |
+| M-TESTPLAN | Archer | Sage | Test plan (Sage has unique spec context) |
+| M-ARCH | Archer | Prism | Architecture + interfaces |
+| M-LOCK | Maestro | User | 3-signal lock (Sage quote-parser + Lex 3 stages + User confirm) |
+| M-DEV | Devon | **Prism → Keeper ★** | Code + unit tests |
+| M-E2E | Shield | **Prism → Keeper ★** | e2e tests (B-level) |
+| M-BUGFIX | Devon | **Keeper ★** | Bug fixes |
+| M-SECURITY | Judge (S-level) | User | Deep security audit |
+| M-MILESTONE | Librarian | Maestro | raw → wiki distillation |
+
+★ **HOLD POINT** — tool-enforced check (`lk` CLI returns 0/1; pipeline doesn't advance until it passes). `★` only marks the PROD gate that blocks merge at commit-time; stage-transition hold points aren't separately marked.
+
+**Principle: implementer ≠ reviewer. Always.**
+
+### Naming
+
+The 12 agents are named for what they do, not for decoration:
+
+| Agent | Meaning | Job image |
+|-------|---------|-----------|
+| **Maestro** | Conductor | coordinates the whole ensemble |
+| **Scout** | Pathfinder | scouts the terrain, verifies preconditions |
+| **Warden** | Gatekeeper | guards the door, confirms exit conditions |
+| **Sage** | The wise | asks Socratic questions |
+| **Lex** | The law | enforces spec-level precision + organizes issues |
+| **Archer** | Marksman / architect | designs the execution path (test-plan + architecture) |
+| **Devon** | Smith | forges code from the fire of tests (R-G-R) |
+| **Prism** | Prism | refracts code through multiple angles (test anti-patterns + security quick scan) |
+| **Judge** | Arbiter | S-grade deep security audit |
+| **Shield** | Shield | writes end-to-end scripts (B-grade) |
+| **Keeper** | Warden of gates | enforces quality gates (commit format + tests + lint + regression) |
+| **Librarian** | Librarian | distills Wiki, preserves project memory |
+
+### Install
+
+> **Platform support**: macOS and Linux only. Windows users: please use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/) or Docker. The installer self-checks `uname -s` and exits with a clear error on unsupported platforms.
+
+```bash
+# Standard pip-based install (recommended): auto-creates venv, sets PATH, links lk to ~/.local/bin
+curl -sSL https://raw.githubusercontent.com/zillionare/louke/main/install.sh | bash
+
+# Or pin a version
+curl -sSL https://raw.githubusercontent.com/zillionare/louke/main/install.sh | bash -s -- v0.3.0
+
+# Or dev mode (clone + editable install)
+git clone https://github.com/zillionare/louke
+cd louke
+./install.sh --editable
+
+# Verify
+lk --help
+```
+
+`install.sh` does 4 things:
+
+1. Creates an isolated venv at `~/.louke/venv/` (no system-Python pollution)
+2. `pip install louke` into that venv
+3. `~/.local/bin/lk` → symlink to venv's `lk`, and appends PATH to your shell rc
+4. Verifies the install + prints uninstall instructions
+
+Uninstall:
+
+```bash
+rm -rf ~/.louke/venv ~/.local/bin/lk
+```
+
+You now have:
+- `lk` CLI (32 commands, 12 agents)
+- `templates/` — 4 doc templates (spec, acceptance, test-plan, security-checklist)
+- `louke/_tools/` — Python scripts wrapped by `lk`
+
+### Use in Your Project
+
+Initialize via `lk scout foundation`:
+
+```bash
+lk scout foundation --repo YOUR_ORG/YOUR_REPO --version v0.1 --spec-id v0.1-001-init
+# → creates .louke/project/project-info.md
+# → creates .louke/project/specs/v0.1-001-init/story.md
+# → opens editor for you to fill in story (interactive)
+```
+
+`lk scout foundation` walks you through:
+1. Step 1 — Collect story/version/repo/DoD (interactive)
+2. Step 2 — Create repo + project + permissions
+3. Step 3 — Verify gh + git identity
+4. Step 4 — Run `lk warden foundation-check` (F1-F11 automated checks)
+5. Step 5 — Commit + push
+
+### Use with Your AI Assistant
+
+`agents/*.md` are written as natural-language agent prompts. Any coding agent that reads instructions can use them.
+
+#### OpenCode
+
+Add the framework as a plugin in `~/.config/opencode/opencode.json`:
+
+```json
+{"plugin": ["louke"]}
+```
+
+#### Claude Code
+
+Place `agents/` under `.claude/agents/` and reference each role via `--agent`:
+
+```bash
+claude --agent agents/Sage.md "interview me about user auth"
+```
+
+#### VSCode (Cursor / Continue / Copilot)
+
+Add the agent prompts to your rules:
+
+```json
+// .continue/config.json
+{
+  "rules": [
+    "agents/Maestro.md",
+    "agents/Sage.md",
+    "agents/Archer.md"
+  ]
+}
+```
+
+In Cursor: **Settings → Rules → Add file → `agents/Sage.md`**
+
+### A Working Session
+
+In a typical session with one of the above AI assistants:
+
+```
+1. lk scout foundation            # Initialize project, verify permissions
+2. "You are Sage. Interview me about user auth."   # AI plays Sage role
+3. lk sage commit-spec --spec ...  # Commit spec + acceptance
+4. lk lex verify-acceptance       # [HOLD POINT] Different agent, tool-enforced
+5. "You are Archer. Write test-plan + arch + interfaces."
+6. lk archer ci-scan              # AC reference + anti-pattern scan
+7. "You are Devon. Implement in R-G-R."
+8. lk devon commit-rgr --phase red/green/refactor
+9. lk keeper gate                 # [HOLD POINT] Tool-enforced commit format
+10. lk judge security-audit       # [HOLD POINT] S-level security review
+11. lk librarian from-raw         # Distill session → wiki
+12. lk maestro status             # Check progress
+```
+
+Each `★` HOLD POINT returns 0 (pass) or 1 (fail). The pipeline doesn't advance until it passes.
+
+### How It Works: One Spec, End to End
+
+Say you want to build user auth:
+
+1. **M-FOUND** (Scout) — `lk scout foundation` creates the repo, GitHub Project, and a Test Issue to verify permissions.
+2. **M-SPEC** (Sage → Lex) — Sage interviews you Socratically (MFA? session timeout? rate limiting?). Lex finds 3 issues. Sage fixes, marks spec locked when **3 signals align**: `lk sage quote-check` exit 0, Lex 3 stages pass, user confirms in IDE.
+3. **M-TESTPLAN** (Archer → Sage) — Archer writes `test-plan.md` with 3-layer testing strategy + AC traceability + anti-pattern rules. Sage reviews (it has unique spec context from M-SPEC).
+4. **M-ARCH** (Archer → Prism) — Archer writes `architecture.md` + `interfaces.md`. Prism checks spec/code consistency.
+5. **M-LOCK** — Spec locked. Implementation begins.
+6. **M-DEV** (Devon → Prism → Keeper) — Devon implements in R-G-R. Each commit prefixed `test: red`, `feat: green`, `refactor`. Prism reviews (cynical + test patterns + security quick scan). Keeper runs `lk keeper gate` (commit format + tests).
+7. **M-E2E** (Shield → Prism → Keeper) — Shield writes e2e (B-level, simple methods: Playwright/testclient/DB). Same Prism + Keeper.
+8. **M-SECURITY** (Judge S-level → User) — `lk judge security-audit` does pattern scan + S-level semantic review. User makes final call.
+9. **M-MILESTONE** (Librarian → Maestro) — `lk librarian from-raw` distills the session to wiki. `lk maestro advance --stage M-MILESTONE` closes the milestone.
+
+Each transition is a different agent. Each hold point is tool-enforced. Each handoff is explicit.
+
+### How louke compares
+
+| Framework | Is spec a contract? | Who reviews | Enforcement layer | spec → code → test loop |
+|---|---|---|---|---|
+| **spec-kit** (GitHub) | spec.md is the source, but no MECE / granularity / traceability constraints | No review | None | Manual + social |
+| **superpowers** (obra, 240k★) | plan.md is plain text, no AC numbering, no commit-time validation | subagent review (same model reviewing itself) | prompt-level self-discipline | TDD indirect guarantee (no ID binding between test and spec) |
+| **oh-my-openagent** (code-yeongyu, 64k★) | agents digest spec themselves | team of agents (same LLM, different prompts) | hooks / middleware | task self-defined, no FR ↔ test binding |
+| **louke** | FR-XXX / AC-XXX-N + `lk archer ci-scan` | 12 different personas (implementer ≠ reviewer, cross-stage context disjoint) | `lk` CLI exit 0/1 (OS process return value) | FR ↔ issue ↔ commit ↔ AC ↔ test end-to-end |
+
+### Architecture (Light)
+
+```
+  agents/*.md              templates/*.md                louke/                louke/_tools/*.py
+  (12 prompts)            (spec, acceptance,           (32 commands,         (Python scripts,
+                          test-plan, security-          12 agents)           wrapped by lk)
+                          checklist)
+       │                       │                            │                      │
+       └───────────┬───────────┴────────────┬───────────────┘                      │
+                   │                        │                                      │
+                   ↓                        ↓                                      ↓
+            AI assistant              Tool-enforced                            wrapped by lk
+         (OpenCode, Cursor,           hold points
+          Claude Code,                 (lk keeper gate,
+          Continue, etc.)               lk judge
+                                      security-audit)
+
+  Two-tier memory:
+    .louke/raw/    →   episodic, per-agent session records
+    .louke/wiki/   →   distilled knowledge, maintained by Librarian
+```
+
+Four things louke doesn't compromise on:
+
+- **12 Agents** = implementer ≠ reviewer; cross-stage context is disjoint
+- **`lk` CLI** = OS-process-level contract; `exit 0/1` is unbypassable
+- **Two-tier memory** = `raw/` (episodic) + `wiki/` (distilled), maintained by Librarian
+- **Promise** = spec → code → test three-segment bidirectional reachability; breakage at any node can be traced to its source
+
+### License
+
+MIT

louke-0.3.0/README.md

@@ -0,0 +1,261 @@
+# louke
+
+> **beyond vibes, into Louke(craft).**
+
+![louke pipeline](docs/hero.svg)
+
+[🇨🇳 中文](README.zh.md) · [🇺🇸 English](README.md)
+
+**louke is a multi-agent collaborative development methodology built on spec-first, test-driven, and tool-aligned agent behavior.** Every stage transition is a tool-enforced check.
+
+---
+
+### Why louke?
+
+You can't build a real software with one-sentence vibecoding.
+
+A real software has hundreds to thousands of sub-requirements, tens of thousands of execution paths and boundary checks.
+
+Real work takes concrete, detailed specs, acceptance criteria, and test plans. Humans must participate in and guide the production of these documents; tools must break them into traceable sub-items so agent code maps one-to-one to those items. Only then can we build a retractable, traceable, trustworthy software production process.
+
+That's the value of louke. Beyond vibecoding — agent programming becomes precision manufacturing, executing every detail you specified perfectly.
+
+When vibecoding:
+
+- You haven't figured out what software you want, yet expect the agent to know
+- Words are always suggestive and leave too much room for imagination, but software must be precise
+- You have many Stories, but neither AI nor you has formed a complete blueprint
+
+Even spec-kit / superpowers / oh-my-openagent don't turn spec into a "programming contract". For spec to be a contract, three things must hold simultaneously — and louke is the only one that achieves them:
+
+- **Sub-requirements are orthogonal** — non-conflicting and non-overlapping, already pruned by Occam's razor
+- **Right-sized granularity** — you can't expect an agent to read a 10,000-word document and still grasp every small detail, unless you break them into items that fit cleanly into a PR
+- **Traceable** — every thread from requirement to code to test must be bidirectionally traceable: forward to find the source, backward to find the landing. Any requirement that can't be matched to its code and tests is a blank check hanging on the wall
+
+And the deepest gap between louke and other frameworks: louke turns this into **Infrastructure-as-Checkpoint** — the traceable loop is not in the AI's self-discipline, but in the forced execution of external CLIs at commit-time. `exit 0/1` is an OS process return value; you can't bypass it. The engineering world only recognizes this one language.
+
+### What louke provides
+
+louke turns the contract's three principles into 5 observable things. Each maps to an `lk` command or a traceable artifact — not just prompts, but tools:
+
+- **spec → GitHub issue, commits must reference issue** — Lex converts each FR into an issue; Devon's commit message enforces `#NNN` format. Requirement to code, one-way trace, never lost
+
+- **test ↔ AC-FRXXXX-YY auto-association, CI static validation closes both directions** — every test docstring must carry an `AC-FRXXXX-YY` ID. `lk archer ci-scan` validates at commit-time: every AC must be referenced by a test, every test must reference an AC. If the loop doesn't close, merge is blocked
+
+- **Anti-pattern CI gate + identity consistency check** — `lk keeper gate` statically scans 8 anti-patterns (`assert True` / `try/except: pass` / no-issue skip / mock-framework core / ...). `lk scout identity-check` locks gh/git identity consistency before workflow start. Violations block
+
+- **Project wiki auto-distillation** — based on LLM compounding engineering, `.louke/raw/` (each agent's session records) → `.louke/wiki/` (structured knowledge). Facts, decisions, current state at a glance, lint-checkable
+
+- **Socratic requirement interrogation** — Sage asks multiple rounds of questions around a vague story until it produces traceable `spec.md` + `acceptance.md`
+
+`louke` defines 12 specialized agents, a 10-stage pipeline, and an `lk` CLI — so every transition is a real check, not the soft "agents review each other". Each agent has its own dedicated toolbox; at every hold point, work is gated for verification.
+
+### The Pipeline
+
+| Stage | Implementer | Reviewer | Notes |
+|---|---|---|---|
+| M-FOUND | Scout | Warden | Project setup + permission gate |
+| M-SPEC | Sage | Lex | spec + FR → issue, Lex reviews + 100% verifies |
+| M-TESTPLAN | Archer | Sage | Test plan (Sage has unique spec context) |
+| M-ARCH | Archer | Prism | Architecture + interfaces |
+| M-LOCK | Maestro | User | 3-signal lock (Sage quote-parser + Lex 3 stages + User confirm) |
+| M-DEV | Devon | **Prism → Keeper ★** | Code + unit tests |
+| M-E2E | Shield | **Prism → Keeper ★** | e2e tests (B-level) |
+| M-BUGFIX | Devon | **Keeper ★** | Bug fixes |
+| M-SECURITY | Judge (S-level) | User | Deep security audit |
+| M-MILESTONE | Librarian | Maestro | raw → wiki distillation |
+
+★ **HOLD POINT** — tool-enforced check (`lk` CLI returns 0/1; pipeline doesn't advance until it passes). `★` only marks the PROD gate that blocks merge at commit-time; stage-transition hold points aren't separately marked.
+
+**Principle: implementer ≠ reviewer. Always.**
+
+### Naming
+
+The 12 agents are named for what they do, not for decoration:
+
+| Agent | Meaning | Job image |
+|-------|---------|-----------|
+| **Maestro** | Conductor | coordinates the whole ensemble |
+| **Scout** | Pathfinder | scouts the terrain, verifies preconditions |
+| **Warden** | Gatekeeper | guards the door, confirms exit conditions |
+| **Sage** | The wise | asks Socratic questions |
+| **Lex** | The law | enforces spec-level precision + organizes issues |
+| **Archer** | Marksman / architect | designs the execution path (test-plan + architecture) |
+| **Devon** | Smith | forges code from the fire of tests (R-G-R) |
+| **Prism** | Prism | refracts code through multiple angles (test anti-patterns + security quick scan) |
+| **Judge** | Arbiter | S-grade deep security audit |
+| **Shield** | Shield | writes end-to-end scripts (B-grade) |
+| **Keeper** | Warden of gates | enforces quality gates (commit format + tests + lint + regression) |
+| **Librarian** | Librarian | distills Wiki, preserves project memory |
+
+### Install
+
+> **Platform support**: macOS and Linux only. Windows users: please use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/) or Docker. The installer self-checks `uname -s` and exits with a clear error on unsupported platforms.
+
+```bash
+# Standard pip-based install (recommended): auto-creates venv, sets PATH, links lk to ~/.local/bin
+curl -sSL https://raw.githubusercontent.com/zillionare/louke/main/install.sh | bash
+
+# Or pin a version
+curl -sSL https://raw.githubusercontent.com/zillionare/louke/main/install.sh | bash -s -- v0.3.0
+
+# Or dev mode (clone + editable install)
+git clone https://github.com/zillionare/louke
+cd louke
+./install.sh --editable
+
+# Verify
+lk --help
+```
+
+`install.sh` does 4 things:
+
+1. Creates an isolated venv at `~/.louke/venv/` (no system-Python pollution)
+2. `pip install louke` into that venv
+3. `~/.local/bin/lk` → symlink to venv's `lk`, and appends PATH to your shell rc
+4. Verifies the install + prints uninstall instructions
+
+Uninstall:
+
+```bash
+rm -rf ~/.louke/venv ~/.local/bin/lk
+```
+
+You now have:
+- `lk` CLI (32 commands, 12 agents)
+- `templates/` — 4 doc templates (spec, acceptance, test-plan, security-checklist)
+- `louke/_tools/` — Python scripts wrapped by `lk`
+
+### Use in Your Project
+
+Initialize via `lk scout foundation`:
+
+```bash
+lk scout foundation --repo YOUR_ORG/YOUR_REPO --version v0.1 --spec-id v0.1-001-init
+# → creates .louke/project/project-info.md
+# → creates .louke/project/specs/v0.1-001-init/story.md
+# → opens editor for you to fill in story (interactive)
+```
+
+`lk scout foundation` walks you through:
+1. Step 1 — Collect story/version/repo/DoD (interactive)
+2. Step 2 — Create repo + project + permissions
+3. Step 3 — Verify gh + git identity
+4. Step 4 — Run `lk warden foundation-check` (F1-F11 automated checks)
+5. Step 5 — Commit + push
+
+### Use with Your AI Assistant
+
+`agents/*.md` are written as natural-language agent prompts. Any coding agent that reads instructions can use them.
+
+#### OpenCode
+
+Add the framework as a plugin in `~/.config/opencode/opencode.json`:
+
+```json
+{"plugin": ["louke"]}
+```
+
+#### Claude Code
+
+Place `agents/` under `.claude/agents/` and reference each role via `--agent`:
+
+```bash
+claude --agent agents/Sage.md "interview me about user auth"
+```
+
+#### VSCode (Cursor / Continue / Copilot)
+
+Add the agent prompts to your rules:
+
+```json
+// .continue/config.json
+{
+  "rules": [
+    "agents/Maestro.md",
+    "agents/Sage.md",
+    "agents/Archer.md"
+  ]
+}
+```
+
+In Cursor: **Settings → Rules → Add file → `agents/Sage.md`**
+
+### A Working Session
+
+In a typical session with one of the above AI assistants:
+
+```
+1. lk scout foundation            # Initialize project, verify permissions
+2. "You are Sage. Interview me about user auth."   # AI plays Sage role
+3. lk sage commit-spec --spec ...  # Commit spec + acceptance
+4. lk lex verify-acceptance       # [HOLD POINT] Different agent, tool-enforced
+5. "You are Archer. Write test-plan + arch + interfaces."
+6. lk archer ci-scan              # AC reference + anti-pattern scan
+7. "You are Devon. Implement in R-G-R."
+8. lk devon commit-rgr --phase red/green/refactor
+9. lk keeper gate                 # [HOLD POINT] Tool-enforced commit format
+10. lk judge security-audit       # [HOLD POINT] S-level security review
+11. lk librarian from-raw         # Distill session → wiki
+12. lk maestro status             # Check progress
+```
+
+Each `★` HOLD POINT returns 0 (pass) or 1 (fail). The pipeline doesn't advance until it passes.
+
+### How It Works: One Spec, End to End
+
+Say you want to build user auth:
+
+1. **M-FOUND** (Scout) — `lk scout foundation` creates the repo, GitHub Project, and a Test Issue to verify permissions.
+2. **M-SPEC** (Sage → Lex) — Sage interviews you Socratically (MFA? session timeout? rate limiting?). Lex finds 3 issues. Sage fixes, marks spec locked when **3 signals align**: `lk sage quote-check` exit 0, Lex 3 stages pass, user confirms in IDE.
+3. **M-TESTPLAN** (Archer → Sage) — Archer writes `test-plan.md` with 3-layer testing strategy + AC traceability + anti-pattern rules. Sage reviews (it has unique spec context from M-SPEC).
+4. **M-ARCH** (Archer → Prism) — Archer writes `architecture.md` + `interfaces.md`. Prism checks spec/code consistency.
+5. **M-LOCK** — Spec locked. Implementation begins.
+6. **M-DEV** (Devon → Prism → Keeper) — Devon implements in R-G-R. Each commit prefixed `test: red`, `feat: green`, `refactor`. Prism reviews (cynical + test patterns + security quick scan). Keeper runs `lk keeper gate` (commit format + tests).
+7. **M-E2E** (Shield → Prism → Keeper) — Shield writes e2e (B-level, simple methods: Playwright/testclient/DB). Same Prism + Keeper.
+8. **M-SECURITY** (Judge S-level → User) — `lk judge security-audit` does pattern scan + S-level semantic review. User makes final call.
+9. **M-MILESTONE** (Librarian → Maestro) — `lk librarian from-raw` distills the session to wiki. `lk maestro advance --stage M-MILESTONE` closes the milestone.
+
+Each transition is a different agent. Each hold point is tool-enforced. Each handoff is explicit.
+
+### How louke compares
+
+| Framework | Is spec a contract? | Who reviews | Enforcement layer | spec → code → test loop |
+|---|---|---|---|---|
+| **spec-kit** (GitHub) | spec.md is the source, but no MECE / granularity / traceability constraints | No review | None | Manual + social |
+| **superpowers** (obra, 240k★) | plan.md is plain text, no AC numbering, no commit-time validation | subagent review (same model reviewing itself) | prompt-level self-discipline | TDD indirect guarantee (no ID binding between test and spec) |
+| **oh-my-openagent** (code-yeongyu, 64k★) | agents digest spec themselves | team of agents (same LLM, different prompts) | hooks / middleware | task self-defined, no FR ↔ test binding |
+| **louke** | FR-XXX / AC-XXX-N + `lk archer ci-scan` | 12 different personas (implementer ≠ reviewer, cross-stage context disjoint) | `lk` CLI exit 0/1 (OS process return value) | FR ↔ issue ↔ commit ↔ AC ↔ test end-to-end |
+
+### Architecture (Light)
+
+```
+  agents/*.md              templates/*.md                louke/                louke/_tools/*.py
+  (12 prompts)            (spec, acceptance,           (32 commands,         (Python scripts,
+                          test-plan, security-          12 agents)           wrapped by lk)
+                          checklist)
+       │                       │                            │                      │
+       └───────────┬───────────┴────────────┬───────────────┘                      │
+                   │                        │                                      │
+                   ↓                        ↓                                      ↓
+            AI assistant              Tool-enforced                            wrapped by lk
+         (OpenCode, Cursor,           hold points
+          Claude Code,                 (lk keeper gate,
+          Continue, etc.)               lk judge
+                                      security-audit)
+
+  Two-tier memory:
+    .louke/raw/    →   episodic, per-agent session records
+    .louke/wiki/   →   distilled knowledge, maintained by Librarian
+```
+
+Four things louke doesn't compromise on:
+
+- **12 Agents** = implementer ≠ reviewer; cross-stage context is disjoint
+- **`lk` CLI** = OS-process-level contract; `exit 0/1` is unbypassable
+- **Two-tier memory** = `raw/` (episodic) + `wiki/` (distilled), maintained by Librarian
+- **Promise** = spec → code → test three-segment bidirectional reachability; breakage at any node can be traced to its source
+
+### License
+
+MIT

louke-0.3.0/louke/__init__.py

@@ -0,0 +1,13 @@
+"""lk - louke CLI.
+
+工具统一入口。每个 agent 一个入口文件 (louke/{agent}.py)，agent prompt 通过
+`lk <agent> {command} [--args]` 调用，避免在 agents/*.md 中出现裸 bash 多步命令。
+
+设计原则:
+1. 每 agent 一个入口文件 (louke/{agent}.py)
+2. agent 不直接调底层脚本，而是通过 `lk <agent>` 调用
+3. 多步命令封装成单个 `lk` 命令，减少出错可能
+4. 子命令内部可用 subprocess 调底层工具 (louke/_tools/*.py)，或实现新逻辑
+5. 退出码遵循 Unix 惯例: 0 = 成功, 非 0 = 失败
+"""
+__version__ = "0.1.0"

louke-0.3.0/louke/__main__.py

@@ -0,0 +1,80 @@
+"""lk CLI entry point.
+
+Usage:
+    lk <agent> <command> [options]
+
+Examples:
+    lk scout identity-check --repo owner/repo
+    lk sage quote-check --spec v0.1-001-init
+    lk warden foundation-check --repo owner/repo --version v0.1 --spec-id v0.1-001-init
+    lk lex verify-acceptance --spec v0.1-001-init
+    lk archer ci-scan --spec v0.1-001-init
+
+设计:
+- 每 agent 一个模块 (louke/{agent}.py)，暴露 register(subparsers) 和 run(args)
+- __main__ 解析 lk <agent> <command>，dispatch 到对应 agent.run()
+"""
+import argparse
+import sys
+
+from . import (
+    scout,
+    sage,
+    warden,
+    lex,
+    archer,
+    keeper,
+    judge,
+    prism,
+    devon,
+    shield,
+    librarian,
+    maestro,
+)
+
+AGENTS = {
+    'scout': scout,
+    'sage': sage,
+    'warden': warden,
+    'lex': lex,
+    'archer': archer,
+    'keeper': keeper,
+    'judge': judge,
+    'prism': prism,
+    'devon': devon,
+    'shield': shield,
+    'librarian': librarian,
+    'maestro': maestro,
+}
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog='lk',
+        description='louke CLI - 工具统一入口（每 agent 一个子命令空间）',
+    )
+    subparsers = parser.add_subparsers(
+        dest='agent', required=True, metavar='<agent>'
+    )
+    for name, module in AGENTS.items():
+        if hasattr(module, 'register'):
+            module.register(subparsers)
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    agent_module = AGENTS.get(args.agent)
+    if not agent_module or not hasattr(agent_module, 'run'):
+        parser.error(f"agent '{args.agent}' 未实现")
+        return 1
+    try:
+        return agent_module.run(args) or 0
+    except Exception as e:
+        print(f"lk {args.agent} {getattr(args, 'command', '?')}: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())