lanternspec 0.1.1

English · 한국어

Install · Quick start · Compared with other SDD tools · Skills · CLI

Hand the work to an AI agent and still be able to follow what was built, why, and how — all the way through.

• 📄 Leaves familiar documents — idea → plan → design → tasks → code, in the document formats teams already know
• 🏮 Illuminates the unknown — compares the technologies the AI used with your own knowledge base and tells you what to review and what to learn
• 📈 Shows the path taken — kanban, timeline and understanding-debt views, all readable in Obsidian

Language note: the documents, skills and CLI messages LanternSpec produces are currently in Korean.

Compared with other SDD tools

Install

Requirements: Python 3.12+ · git · uv

uv tool install lanternspec      # installs the lantern command
cd my-project
lantern install                  # installs skills, rules and hooks into this project (Claude Code by default)

Then call /l-init inside your AI tool ($l-init in Codex).

• Using several AI tools: lantern install --tools claude,codex,antigravity
• Skills live in your project: they are written straight into the project, not installed as a plugin. So they are called without a prefix (/l-init) and shared with your team through git.
• When a new version comes out: uv tool upgrade lanternspec → lantern upgrade

Quick start

/l-init                       answer 7 questions → lantern.yaml · docs/ · draft project definition · design principles
/l-idea dark mode support     record an idea right away → 1. 아이디어/IDEA-001
/l-plan IDEA-001              what and why, with acceptance criteria → 2. 작업/W-001 …/기획.md
/l-design W-001               how — only the structure, screens and data that change; a person approves
/l-task W-001                 an ordered task list
/l-build W-001                implement → test → one commit per task, report with evidence → merge into the current state
/l-report                     kanban · timeline · debt · a three-line status report

lantern numbers every document in order.

Commands for checking where you are

Flow and skills

flowchart LR
  S["⚙️ /l-init"] --> I
  subgraph W["🛠 Work flow"]
    I["💡 /l-idea"] --> P["📋 /l-plan"] --> D["📐 /l-design"] --> T["✅ /l-task"] --> B["🔨 /l-build"]
  end
  P & D & B -.unfamiliar tech.-> L["🧭 /l-learn"]
  B -->|merge when done| C["📘 3. Current state"]
  W & L --> R["📊 /l-report"]

How it works

• Scripts handle the format, the AI writes the content. Numbering, files, folders, checks and status changes all go through the lantern command; the AI only writes content.
• Every document starts from a template. The AI fills in the template's {{blanks}}; changing the section structure is flagged immediately.
• Every skill ends the same way. A skill that changed documents runs lantern close <skill>: check → update the map → log the run.
• Show before writing. Designs and changes to the current state are summarised and approved first (/l-idea is the only exception).
• Your knowledge base is read-only. Notes are written only after you approve.

Document structure

Documents are stored in one folder per work item, and the MOC (document map) collects them by stage. Folder and file names are Korean.

docs/
├─ 개발문서 MOC.md        document map + view by stage (lantern map rewrites the marked part)
├─ 0. 템플릿/              templates you refine over time · _meta/enums.yaml (the single source of status and kind names)
├─ 1. 아이디어/            ideas
├─ 2. 작업/W-001 …/        plan · design · tasks · log — the only place edited while working
│   └─ 보관/              archive
├─ 3. 현재 상태/           what the system looks like now — updated only when work is done, after approval
├─ 4. 운영 기록/           reports · session logs · (teams of 2+) meeting notes
├─ 5. 기존 문서/           (existing projects) original documents, kept unchanged
└─ 📒 부채/               understanding debt — one card per debt

Which documents you get depends on your /l-init answers (lantern.yaml; check with lantern profile docs).

• A mobile app adds deployment and platform-integration documents.
• A team of two or more adds collaboration rules and meeting notes.

If you don't want documents on the remote, use lantern docs-mode local. Documents then live only on a docs-local branch in the same repository, and pushing that branch is blocked.

Viewing the docs in Obsidian

Open the docs/ folder as a vault in Obsidian and it is already set up for reading (docs/.obsidian/).

• Folder colors, callouts and quotes — each document stage has its own folder color, and callouts and quotes look clean. Works on top of any theme.
• Picking status and kind — each document type offers only its own choices in a menu (Metadata Menu). The choices are generated from enums.yaml, so renaming a value updates them too.
• Recommended plugins — Dataview (shows [start:: …] fields in task lists) and Metadata Menu (choice menus). /l-init asks whether to download them; to do it later:

lantern obsidian plugins     # downloads the latest official release files of both plugins into docs/.obsidian/plugins/

When Obsidian first asks whether to turn on community plugins, turn them on (leave restricted mode). Plugin code and the window layout (workspace.json) stay out of git; only the settings are committed. Teammates run the same command.

Supported AI tools

• Rules live in AGENTS.md. LanternSpec manages only the <!-- lanternspec:start --> block inside it and leaves everything outside the block alone.
• Codex and Antigravity share the skills folder. When you use both, skill bodies say /l-build, and AGENTS.md tells Codex to use $ instead.

Keeping documents and code in line

git and AI tools already have hooks: they run a script at set moments (just before a commit, right after a file is written, and so on).

LanternSpec connects its checks to those hooks, so lantern checks at every stage that documents and code still match. The checks are done by a script, not by the AI, so they always apply the same rules.

• Warnings by default. Work is never blocked. To make the commit checks blocking, set git.hooks to block in lantern.yaml.
• Hard-to-undo mistakes are always blocked. For example, pushing documents you chose to keep off the remote is blocked regardless of settings.

lantern hooks install            # turns on the commit and push checks (/l-init asks before installing)
lantern install --ci             # also checks on GitHub (turn off with --no-ci)

Managing unfamiliar tech — knowledge base and understanding debt

When the AI uses a technology you don't know, LanternSpec compares it with the notes in your knowledge base and sorts it into three groups.

• 🟢 you have a note → links the note
• 🟡 you have a note but asked again → tells you what to review
• 🔴 no note yet → suggests a draft study note

Anything you don't understand yet is kept as a debt card, and every time you ask about it again the count goes up.

Every knowledge base supports the same four actions: search · read · propose · write. The CLI (lantern knowledge …) and the MCP server (lantern mcp) use the same functions.

There are three kinds of debt.

Design principles and ways of working

Design principles and code conventions

Picks design principles and code conventions from a table, based on the project kind chosen in /l-init and the measured size (lines of code · team size).

• Languages: Python · TypeScript · Swift · Rust · Go
• The essentials go into AGENTS.md; the full explanation goes into 개발 원칙.md (design principles).
• In existing projects, lint and format settings already in use are recorded, never changed.
• When the code grows past a size boundary, lantern doctor asks whether to raise the principles one level.
• See the result with lantern principles show; run lint and type checks with lantern lint

How the AI works

lantern harness suggest looks at code size, work in progress, whether tests exist and past runs, and recommends one of three modes.

• Harness: small loops inside one task. The default for small projects
• Loop: reruns the whole work item until the acceptance tests pass
• Graph: splits independent work items into worktrees so several agents work at the same time

Evaluation

lantern eval uses the run log to compare cost (time · tool calls) and results (format errors at wrap-up) per skill, model and setting.

Design tools

Claude Design, Figma and Canva through each tool's MCP. Import mockups with lantern screen import; lantern screen compare finds where the built screen differs from the mockup.

CLI at a glance

setup      install [--tools] [--mcp] [--ci|--no-ci] · upgrade · doctor · harness suggest
profile    profile show|docs|write|set · principles show|detect · enums list|rename
documents  scaffold init [--plan] | work | doc | idea | adr | meeting | custom · new-id · map · meta get|set
checks     check [--changed] [--epic W-012] · lint · check-dbml · dbml render|from-sql|diff
work       task next [--all]|start|done|ac|list|estimate · task add [--parallel] · pack · screen import|compare
           work branch|start|list|finish|archive|stage · design approve · unit-log add · idea find|status
learning   knowledge search|read|propose|write|areas · debt find|new|ask|resolve|promote|practice|known|status|list · mcp
reports    report [--views] [--summary] · status · scan [--tests] · sync adopt · eval · obsidian plugins
templates  template list|lint|level|bump|outdated|diff|usage|new|migrate · legacy adopt|todos
git        hooks install|uninstall|status · docs-mode local|shared
wrap-up    close <skill>

License

MIT