Lòukè - beyond vibes, into Lòukè(craft)

🇨🇳 中文 · 🇺🇸 English

Lòukè is a spec-first, test-driven, tool-aligned multi-agent collaborative development method.

louke has not yet reached a level suitable for official release. Please refrain from installing and using it in your projects for now. It is expected to become fully functional within two weeks.

You can't build real software with a one-line vibe-coding prompt. When vibecoding:

• You haven't figured out what you want, yet you expect the agent to know
• Words are suggestive and leave too much room for imagination, but software must be precise
• You tell many Stories, but neither the AI nor you has formed a complete blueprint

Real software has hundreds to thousands of sub-requirements and tens of thousands of execution paths and boundary conditions.

We must rely on 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 is the value of Lòukè. Beyond vibecoding — agent programming becomes precision manufacturing, executing every detail you specified perfectly.

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:

• Sub-requirements are orthogonal — non-conflicting and non-overlapping, already pruned by Occam's razor.
• Right-sized granularity — an agent cannot read a 10,000-word document and still grasp every small detail, unless you break items into tasks 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 without matching code and tests is a blank check hanging on the wall.

And Lòukè differs from these frameworks in philosophy: Lòukè 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.

Programmers make mistakes — that's why we have tests. Agents make mistakes too. Don't rely on AI self-discipline; rely on rigorously aligned specs and tools.

Lòukè turns the contract's three principles into five 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 agent 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 agent keeper gate statically scans 8 anti-patterns (assert True / try/except: pass / no-issue skip / mock framework core / ...). lk agent 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

Lòukè 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.

• 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

★ 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 are not separately marked.

Principle: implementer ≠ reviewer. Always.

M-SPEC is not "Sage produces spec → Lex reviews once at the end." Lex runs three phases at three distinct trigger points. Maestro must actively trigger Phase 1 and Phase 3 (Phase 2 is handed off by Sage Step 6, but still routed through Maestro). Skipping any phase makes the M-LOCK Lex signal invalid.

sequenceDiagram
    participant U as User
    participant M as Maestro
    participant S as Sage
    participant L as Lex

    U->>M: Story ("add user auth")
    M->>S: M-SPEC start
    S->>U: Step 1: ≤7 questions in chat
    S->>S: Step 2: draft spec.md + acceptance.md
    S->>U: Step 3: inline quote clarification (≤5 rounds)
    S->>S: Step 4: add HTML anchors
    S->>S: Step 5: create GitHub issues + link Project
    Note over M: Maestro triggers Lex Phase 1
    M->>L: verify-acceptance (L1-L5) + quote-check
    L-->>M: [pass] / [reject]
    alt Phase 1 rejected
        M->>S: fix spec.md (forward tool stderr)
        S->>S: fix
        M->>L: re-run Phase 1
    end
    S->>S: Step 6: quote-check exit 0 → handoff
    Note over S: Sage Step 6 notifies Lex Phase 2 (via Maestro)
    M->>L: issue coverage + Project link check
    L-->>M: [pass] / [reject]
    alt Phase 2 rejected
        M->>S: create/link missing issues
        S->>S: fix
        M->>L: re-run Phase 2
    end
    Note over M: Maestro triggers Lex Phase 3
    M->>L: verify-issue (L1-L8 schema)
    L-->>M: [pass] / [reject]
    alt Phase 3 rejected
        M->>S: fix issue schema fields
        S->>S: fix
        M->>L: re-run Phase 3
    end
    Note over M: 3 signals: Sage quote-check ✓ + Lex 3 phases ✓
    M->>U: M-LOCK: confirm spec lock
    U-->>M: confirmed
    M->>M: advance to M-TESTPLAN

Key rules:

• Phase 1 failure → fix spec only; Phase 2 failure → fix issues only; Phase 3 failure → fix issue schema fields only
• If a fix reveals an upstream root cause → regress to M-SPEC and re-run from Phase 1
• Maestro forwards tool raw output (stderr/stdout) to Sage on rejection — never paraphrases

Each agent has a default primary model (with an in-tier fallback). Override via ~/.louke/models.json (user-level) or .louke/models.json (project-level); use lk models list / lk models doctor to check current bindings, lk models bind <abstract> <full> to override.

5 agents have explicit permission: blocks (YAML object, 11-13 keys) constraining their tool access. The other 7 also have explicit blocks (11 keys each) — all 12 agents declare their permissions explicitly. All 11 subagents have task: deny to enforce "Maestro is the sole orchestrator" design.

Run lk agent lint to verify all agent frontmatter conforms.

Maestro is the only mode: primary agent. The other 11 agents are mode: subagent — they do not appear in OpenCode's <Leader>a list and cannot be selected as primary. Maestro orchestrates them via the task tool.

• Users see only Maestro in <Leader>a
• Maestro dispatches work to subagents in isolated child sessions
• Subagent question calls bubble to the main window (verified 2026-07-03)
• Users never need to press <Leader>a to switch primary agents
• After a subagent completes, focus auto-returns to Maestro
• For viewing a subagent's context, press <Leader>+Down to enter / <Leader>+Up to return

Platform: macOS / Linux. Windows users: please use WSL2 or Docker. install.sh self-checks uname -s and exits with a clear error on unsupported platforms.

# 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 four 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: rm -rf ~/.louke/venv ~/.local/bin/lk

# New project (creates <name>/ dir with .louke/ skeleton + OpenCode agents + issue template + CI workflow)
lk init my-project
cd my-project

# Adopt existing git repo (non-destructive, adds .louke/ alongside your code)
cd ~/work/my-existing-repo && lk init .

lk init does:

1. Scaffolds the project layout (.louke/{templates,project,project/specs,wiki/pages,wiki/decisions,raw}/)
2. Copies louke's bundled templates (spec / acceptance / prd / bug-fix / …) into .louke/templates/
3. Installs .github/ISSUE_TEMPLATE/feature.yml (4-digit FR schema) + .github/ISSUE_TEMPLATE/bug.yml
4. Writes default_agent: maestro to project-level opencode.json
5. Generates .opencode/agents/*.md from the louke package's installed agent prompts (each agent with its resolved model: field). Re-run with lk board opencode any time you upgrade louke.
6. Optionally installs the daily wiki-distillation cron (--no-cron to skip)

Agents are package-owned. The 12 agent prompts live inside the installed louke Python package — there is intentionally no project-side copy you can (or should) edit. lk board opencode materialises them into .opencode/agents/ so OpenCode can consume them. Past attempts to let projects override agents were removed because they caused stale-format drift.

Then start OpenCode — the default primary agent is Maestro. Just tell it what you want in chat, for example:

"We want to add user authentication — username/password login, plus Google login."

From here on, Maestro orchestrates the entire pipeline. You don't need to switch agents manually; Sage's follow-up questions and Judge's security findings all flow back to you through Maestro.

Using "add user authentication" as an example, the timeline unfolds linearly:

1. M-FOUND — lk agent scout foundation creates repo, GitHub Project, Test Issue to verify permissions
2. M-SPEC — Sage asks follow-ups in chat (MFA? session timeout? rate limiting?); Lex finds 3 structural issues; Sage fixes them. Locked when 3 signals align: lk agent sage quote-check exit 0 + Lex 3 stages pass + your IDE confirmation
3. M-TESTPLAN — Archer writes test-plan.md (3-layer strategy + AC traceability + anti-pattern rules); Sage reviews (holds M-SPEC's unique context)
4. M-ARCH — Archer writes architecture.md + interfaces.md; Prism checks spec/code consistency
5. M-LOCK — Spec locked. Implementation begins
6. M-DEV — Devon codes R-G-R. Each commit prefixed test: red / feat: green / refactor. Prism reviews (anti-patterns + security quick scan); lk agent keeper gate checks commit format + tests
7. M-E2E — Shield writes e2e (B-level, fixed methods: Playwright/testclient/DB); same Prism + Keeper
8. M-SECURITY — lk agent judge security-audit does pattern scan + S-level semantic review. You make the final call
9. M-MILESTONE — lk agent librarian distill distills the session to wiki; lk agent maestro advance --stage M-MILESTONE closes the milestone

Each step is a different agent; each hold point is tool-enforced; each handoff is an explicit trace.

The above flow is automatically orchestrated by Maestro — you just tell Maestro in OpenCode "do user authentication," and it will sequentially invoke Scout/Sage/Lex/Archer/Devon/Shield/Judge/Librarian. Below is what you see (through your conversation with Maestro) at each step.

New models are released every month. You may need to dynamically adjust agent models. Each agent has a default model; switching coding agents to local small models in day-to-day development saves most of the tokens.

# View current bindings
lk models list
lk models doctor            # Check for missing/failed resolutions

# Temporarily switch an agent to a cheaper model
lk models bind devon kimi-2.7-code
lk models unbind devon       # Restore default

models.json priority: project-level (.louke/models.json) > user-level (~/.louke/models.json).

After receiving the Story, Sage immediately starts a round of requirement clarification in the chat window, but will ask fewer than 7 questions. Deeper questions are better clarified outside of chat. Lòukè brings back the inline comment style from email.

We use Markdown quote blocks to start the discussion:

### FR-0100 Draw a circle

| Valid | Testable | Decided |
| ----- | -------- | ------- |
| ✅     | ✅        | ⚠️       |

You shall draw a circle with a radius of 0.5m.

> Sage: How should the pen color and stroke width be determined?

Sage thinks this requirement is not clear enough to verify. So he asks: how should the pen color and stroke width be determined?

You reply with one more level of > indentation:

> Sage: How should the pen color and stroke width be determined?
>> Aaron: Provide a toolbar and let the user choose
>>> Sage: Requirement confirmed.

This is standard email threading syntax. If you think the spec wording is wrong and doesn't need discussion, you can directly edit the spec; Sage will find your changes through git diff, and if there are any questions, will open a session.

Lòukè uses GitHub Projects to manage releases. A release starts with a Story. Sage breaks down the requirements, creates GitHub issues, and automatically links them to the GitHub Project. Release Notes naturally derive from this project.

We also throw in a small gift — by creating a project named {repo}-backlog, we give you an idea collection box. If you have an inspiration that can't fit into the current release, you'll find this project surprisingly useful. Future releases start their planning from here.

lk agent scout foundation creates two Projects per repo:

• {repo}-{version} — per-release, tracks the current milestone's issues
• {repo}-backlog — per-repo (permanent), holds unscheduled ideas

Issues created with gh issue create --no-milestone naturally land in the backlog; during planning, pull backlog issues into the current release with gh project item-add.

Lint, format, typecheck, and tests run automatically at commit time via the project's .pre-commit-config.yaml — no tokens spent, no manual invocation. Bypassing hooks with --no-verify is an anti-pattern because it breaks the Infrastructure-as-Checkpoint contract. See louke/templates/pre-commit/README.md for the bundled templates.

lk init my-project # New project lk init . # Adopt existing repo lk agent scout foundation --repo owner/repo --version v0.1 --spec-id v0.1-001-init lk agent scout identity-check --repo owner/repo lk agent scout invite-owner owner/repo --version v0.1

lk agent maestro status # View current stage lk agent maestro advance --stage M-DEV # Advance to next stage lk agent maestro regress --stage M-SPEC --reason "spec missing NFR" lk agent maestro escalate --reason "user unresponsive for 3 rounds"

lk agent archer ci-scan --spec ID # AC traceability validation lk agent keeper gate # commit format + R-G-R order + anti-pattern scan lk agent judge security-audit --release releases/v0.1

lk models list # View agent→model bindings lk models doctor # Diagnose missing/failed resolutions lk models bind devon kimi-2.7-code # Temporary override lk models unbind devon

lk agent librarian lint # Health check lk agent librarian distill # Distill raw sessions to wiki pages

lk: command not found — ~/.local/bin is not in PATH. Add export PATH=$HOME/.local/bin:$PATH to your shell rc and source it (or restart your terminal).

lk agent scout foundation fails with gh not authenticated — Run gh auth login first, then lk agent scout identity-check to verify.

Sage keeps asking about the same requirement — Possible causes:

• Your reply didn't use an extra level of > indentation, so Sage didn't recognize it as a new reply
• You directly edited the text — Sage will discover the change through git diff and ask for confirmation. Reply with "✓ resolved" on the changed section

Commit blocked by lk agent keeper gate — The terminal prints which anti-pattern was hit. Common causes:

• Commit message doesn't follow R-G-R prefix conventions (e.g., wrote feat: add login instead of feat: green add login)
• feat: green appears before test: red (R-G-R order violation)
• Test docstring missing AC-FRXXXX-YY
• Wrote assert True / try/except: pass / mocked framework core

OpenCode doesn't show the 12 agents after launch — Check the .opencode/agents/ directory and opencode.json's default_agent field; rerun lk init --force if needed.

Wondering "where are we now" — lk agent maestro status tells you in one line.

• #78 — .louke/project as a standalone private GitHub repo (via git submodule), separating spec/wiki from public code
• #79 — louke serve web UI for browsing/editing wiki / spec / acceptance / test-plan

MIT

Louke releases follow Semantic Versioning. The CLI (lk) self-updates via pip install --upgrade louke; project-local state (.louke/, ~/.louke/models.json) is preserved across upgrades. Agent prompts come from the installed package, so upgrading louke automatically ships any agent-prompt changes — re-run lk board opencode to refresh .opencode/agents/.

12 specialized agents, 10-stage pipeline (M-FOUND → M-MILESTONE), lk init / lk agent scout foundation / lk agent archer ci-scan / lk agent keeper gate, OpenSpec-style YAML issue template, 129 bats tests.

For older (pre-v0.6) release notes, see .github/RELEASE_NOTES_v0.X.md.