dna-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{dna_cli-0.1.0 → dna_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dna-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: DNA command-line interface — the `dna` binary for the declarative SDLC + document CRUD (kernel-local, no service required)
 Project-URL: Homepage, https://ruinosus.github.io/dna/
 Project-URL: Repository, https://github.com/ruinosus/dna
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: <3.14,>=3.12
 Requires-Dist: click>=8.1.0
-Requires-Dist: dna-sdk<0.2,>=0.1
+Requires-Dist: dna-sdk<0.3,>=0.2
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Provides-Extra: dev

{dna_cli-0.1.0 → dna_cli-0.2.0}/dna_cli/__init__.py

@@ -19,6 +19,7 @@ from dna_cli import (
     doc_cmd,
     docs_cmd,
     eval_cmd,
+    init_cmd,
     install_cmd,
     kind_cmd,
     memory_cmd,
@@ -79,6 +80,7 @@ from dna_cli import pr_cmd as _pr_cmd  # noqa: E402,F401
 # the GitHub Issues side of the symbiosis (bridge with provenance).
 from dna_cli import issue_bridge_cmd as _issue_bridge_cmd  # noqa: E402,F401
 main.add_command(source_cmd.source)
+main.add_command(init_cmd.init)
 main.add_command(install_cmd.install)
 main.add_command(eval_cmd.eval_)
 

dna_cli-0.2.0/dna_cli/data/onboarding-scope/AGENTS.md

@@ -0,0 +1,68 @@
+# AGENTS.md — how work is tracked in this project
+
+This project uses [DNA](https://github.com/ruinosus/dna) (Domain Notation of
+Anything) to track its own lifecycle: Stories, Features, Epics and Issues are
+declarative YAML documents in the board scope under `.dna/`, written and
+transitioned via the `dna sdlc` CLI. This file was materialized by `dna init`
+and is itself a live `agents.md/v1` instance the DNA SDK parses and
+round-trips byte-faithfully.
+
+## SDLC protocol — work is tracked in-repo via `dna sdlc`
+
+The flow is **story-first**: file the Story before the work, narrate while
+building, verify before closing.
+
+```bash
+dna sdlc brief                          # session start — what's in flight
+dna sdlc hooks install                  # one-time per clone — commit trailers
+dna sdlc feature create f-my-area --title "..." --desc "..."   # parent Feature
+dna sdlc story create s-my-work --feature f-my-area --desc "..." \
+  --ac "Given/When/Then ..." --dod "code+tests+docs ..."   # AC + DoD required
+dna sdlc story start s-my-work --plan "plan of attack"      # plan gate
+dna sdlc story comment s-my-work --body "decided X because Y"  # narrate as you go
+dna sdlc test-guide create tg-my-work --verifies Story/s-my-work --step "run :: expect"
+dna sdlc test-run record tg-my-work --outcome pass          # test gate for done
+dna sdlc story pr s-my-work             # gh pr create, pre-filled FROM the story
+dna sdlc story done s-my-work           # only after the PR merges
+```
+
+While a story is active, every commit is stamped with `Work-Item:` +
+`dna-sdlc[bot]` trailers by the versioned hook — that is the provenance
+seal linking git history to the work item (`dna sdlc story commits s-x`).
+
+## Conventions
+
+- **Story-first.** Non-trivial work starts with `dna sdlc story create`
+  (AC + DoD are mandatory at create time) and `story start` (the plan
+  gate — substantial work gets a real plan via `--plan-file`, not a
+  one-liner).
+- **Narrate as you go.** Status changes record *that* something happened,
+  not *what*. Post `dna sdlc story comment` for each meaningful step or
+  decision — the timeline is what stakeholders and future sessions read.
+- **Gapless definition of done.** Never mark a story `done` with a gap:
+  finish to market standard, or keep it `in-progress` / decompose into
+  tracked child stories. `story done` requires a passing TestRun
+  (`--allow-no-tests` is for recorded exceptions only).
+- **Review = open PR; done = merged.** `story review` expects an open PR
+  on the branch; a story in `review` with no PR is stale. Once a PR is
+  approved, stop pushing to its branch — further work goes to a new branch.
+- **Surface IDs.** Print full slug IDs in backticks (`s-foo`, `i-012-bar`)
+  so they are paste-able into `dna sdlc story show` / `git log --grep`.
+
+## Do not
+
+- **Never hand-edit `.dna/**.yaml` for status changes** — the CLI is the
+  canonical write path (validation, timeline and journey events fire there).
+- **Never do non-trivial work without an active story** — unstamped commits
+  are invisible to `story commits` / `story show`; absence is signal.
+- **Never mark a story `done` with a gap** — finish to market standard or
+  keep it `in-progress` / decompose into tracked child stories.
+
+## Learn more
+
+- Skill: the `dna-sdlc-cli` skill (agentskills.io SKILL.md format) is
+  materialized by `dna init` into your agent tool's skills directory —
+  `.claude/skills/`, `.github/skills/`, `.cursor/skills/` or
+  `.opencode/skills/` — with the full workflow. Same content everywhere.
+- Docs: <https://ruinosus.github.io/dna/> — CLI reference, Kinds guide,
+  SDLC guide ("Your git log is your SDLC").

dna_cli-0.2.0/dna_cli/data/onboarding-scope/skills/dna-sdlc-cli/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: dna-sdlc-cli
+description: "Use whenever work in this project needs SDLC tracking (Epic, Feature, Story, Issue, Spec, Plan, Spike, TestGuide/TestRun), or the user asks to file/start/narrate/close lifecycle docs, open a story PR, or wire the git hooks. Operate via the `dna sdlc` CLI \u2014 never edit `.dna/` YAMLs by hand for status changes; the CLI is the canonical write path (validation, timeline events and the derived journey fire correctly)."
+---
+
+# DNA SDLC CLI — the work tracker for this project
+
+This project tracks its own lifecycle as DNA documents: Stories, Features,
+Epics and Issues are first-class YAML documents in the board scope under
+`.dna/` (the CLI's default source `./.dna` — run `dna` from the project
+root, no env var needed; the sole board scope is auto-detected, or set
+`DNA_SDLC_SCOPE`). Don't manually edit those YAMLs when changing status —
+the CLI is the canonical write path.
+
+## ⚖️ Maxim — zero gaps (the supreme rule)
+
+**Never ship an activity with a gap.** Every Story/Feature/Epic/Issue is
+either finished to market standard with no gaps, or it **stays
+`in-progress`** until it is. There is no "ship with a TODO for later"
+without a tracked Story covering it.
+
+Before `story done`, the work must satisfy its own AC + DoD — close them
+granularly with evidence:
+
+```bash
+dna sdlc story check s-foo --ac 1 --dod "tests" --evidence "PR #42"
+dna sdlc story check s-foo --all --evidence "commit abc123 + CI green"
+```
+
+When a gap appears mid-story:
+
+1. **Small + adjacent** (lint fix, doc tweak): include in the same Story.
+2. **Medium + orthogonal**: file a follow-up Story; current one goes
+   `dna sdlc story block s-foo --reason "waiting on s-foo-followup"`.
+3. **Large + systemic**: file a Feature; the Story stays blocked until its
+   first covering Story ships.
+
+## Vocabulary
+
+| Kind | Equivalent | Slug prefix | Verb group |
+|------|------------|-------------|------------|
+| Initiative / Roadmap | Initiative | free-form | `initiative` |
+| Epic | Epic | `e-...` | `epic` |
+| Feature | Feature | `f-...` | `feature` |
+| Story | User Story | `s-...` | `story` |
+| Issue | Bug/Task/Question | `i-NNN-...` (auto-numbered) | `issue` |
+| Spec / Plan | RFC / implementation plan | free-form | `spec` / `plan` |
+| Spike | time-boxed investigation | `sp-...` | `spike` |
+| TestGuide / TestRun | test script / execution record | `tg-...` / `tr-...` | `test-guide` / `test-run` |
+
+Story statuses: `needs-triage | todo | in-progress | review | done | blocked
+| deferred | cancelled`. Issue arc: `file → triage → start → resolve`.
+
+**Command shape:** *listing* is `dna sdlc list <Kind>` (capital-K:
+`list Story --status in-progress`, `list Issue`); *acting on one doc* is
+`dna sdlc <noun> <verb> <name>` (`story start`, `issue resolve`,
+`feature`/`epic` verbs via their groups). There is no `story list`. When
+unsure: `dna sdlc <noun> --help`.
+
+## Session start
+
+```bash
+dna sdlc brief      # one-screen bootstrap: in-flight work, spikes, lessons, hot issues
+dna sdlc current    # every doc currently in-progress
+dna sdlc next       # snapshot of active work
+```
+
+## The story-first lifecycle
+
+### 1. File it — AC + DoD are required at create time
+
+```bash
+dna sdlc story create s-my-work \
+  --feature f-parent \
+  --desc "what and why, one line" \
+  --priority high --labels cli,docs --reporter my-agent \
+  --ac "Given/When/Then acceptance criterion" \
+  --dod "code + tests green + docs updated"
+```
+
+The CLI refuses Stories without `--ac`/`--dod` (exit criteria are not
+optional). `--ac`/`--dod` are repeatable. Bugs/tasks are Issues:
+`dna sdlc issue file --slug my-bug --type bug --severity high --desc "..."`.
+
+### 2. Start it — the plan gate
+
+```bash
+dna sdlc story start s-my-work --plan "plan of attack in 1-3 lines"   # inline Plan
+dna sdlc story start s-my-work --plan-file plan.md                    # rich multi-section plan
+dna sdlc story start s-my-work --no-plan --skip-reason "1-line hotfix"  # honest, recorded skip
+```
+
+Substantial work gets a real plan (`--plan-file`), not a one-liner. Side
+effect: `story start` stamps `.dna/active-story.txt`, which the git hook
+reads (below).
+
+### 3. Build — narrate as you go
+
+Status changes record *that* something happened, not *what*. Post a comment
+for each meaningful step or decision — the timeline is what stakeholders
+(and future sessions) read:
+
+```bash
+dna sdlc story comment s-my-work --body "now refactoring the cache to LRU"
+dna sdlc story comment s-my-work --body "decided maxsize=64 because scans are heavy" --type decision
+```
+
+`--type` auto-detects decision-shaped comments; `--commit-ref` ties a note
+to a SHA (auto-detected from HEAD). The transition verbs (`start`, `review`,
+`done`) warn when the timeline went mute — narrate inline with `--note "..."`.
+
+### 4. Verify — the test gate
+
+`story done` **requires a passing TestRun** that verifies the Story
+(mirroring the AC/DoD guard at create):
+
+```bash
+dna sdlc test-guide create tg-my-work --description "what it validates" \
+  --verifies Story/s-my-work --step "run X :: expect Y" --step "run Z :: expect W"
+dna sdlc test-guide create tg-my-work --from-ac s-my-work   # or stub steps from the AC
+dna sdlc test-run record tg-my-work --outcome pass --note "all green locally + CI"
+```
+
+Escape hatch `story done --allow-no-tests` is for recorded exceptions only.
+
+### 5. PR — born from the story, review = open PR
+
+```bash
+dna sdlc story pr s-my-work              # gh pr create, pre-filled FROM the story
+dna sdlc story pr s-my-work --dry-run    # print title + body, no gh call
+dna sdlc pr-footer s-my-work             # just the attribution footer, for hand-made PRs
+dna sdlc story review s-my-work          # requires an open PR on the branch (or --no-pr --reason)
+```
+
+`story pr` assembles title (`feat(<label>): <title> (<s-x>)`), body
+(description + AC as a checklist) and the attribution footer, then stamps
+the PR URL back onto the timeline. **PR ready = stop pushing to its
+branch** — squash-merge captures the branch at the merge click; commits
+pushed after approval are silently dropped. Further work goes to a new
+branch off the merged base.
+
+### 6. Done — only after merge
+
+```bash
+dna sdlc story done s-my-work --summary "what shipped"
+```
+
+A Story in `review` with no open PR is stale; `done` before the merge is a
+lie. `done` auto-stamps `commit_ref`, warns on empty outputs (link
+artifacts via `dna sdlc produces add`), and honors the test gate.
+
+## Git symbiosis — trailers close the git↔SDLC loop
+
+```bash
+dna sdlc hooks install    # one-time per clone → git config core.hooksPath scripts/git-hooks
+dna sdlc hooks status     # show wiring: hooksPath, active story, coauthor
+```
+
+While a Story is active, every `git commit` is stamped with
+`Work-Item: Story/<name>` + the `dna-sdlc[bot]` co-author trailer. No
+active story → no stamp (absence is signal). The way back needs no
+bookkeeping:
+
+```bash
+dna sdlc story show s-my-work      # header + AC/DoD + plan + recent timeline
+dna sdlc story commits s-my-work   # every commit tied to the Story (trailers + timeline)
+```
+
+## Surface IDs in chat (always)
+
+When starting or shipping a doc, print the **full slug ID in backticks**
+(`s-foo-bar`, `i-012-some-bug`) so the human can paste it into
+`dna sdlc story show` / `git log --grep`. After a chunk of work, list each
+ID touched with its transition (`s-foo: todo → done`).
+
+## Other verbs (one-liners — `dna sdlc <verb> --help`)
+
+`epic` / `feature` / `initiative` (parents; `feature` rolls up child
+Stories) · `spike` (investigation arc: comment → answer with findings +
+follow-up) · `adr` / `spec` / `plan` (design docs, ADR-style statuses) ·
+`kaizen` (continuous-improvement observations) · `journey` (phase ledger —
+derived; rarely needs manual writes) · `demand` (Story + journey-discover
+in one shot) · `produces` / `cite` (link artifacts / sources) ·
+`changelog` (release notes per scope) · `extract-decisions` (mine timelines).
+
+## When NOT to use this skill
+
+- Reading documents programmatically (use the SDK: `Kernel.quick(...)` /
+  `mi.all("Story")` — see the dna-sdk docs).
+- Bulk renames/deletes (use `dna doc` + a git commit, not the SDLC verbs).

dna_cli-0.2.0/dna_cli/init_cmd.py

@@ -0,0 +1,355 @@
+"""``dna init`` — agent-ready onboarding for a consumer project.
+
+``pip install dna-sdk dna-cli`` delivers a working kernel + CLI, but the
+project's AI agent arrives blind: the SDLC skill, the AGENTS.md conventions
+and the git hooks live in the DNA repo, not in the packages. ``dna init``
+closes that gap with one command, and it does so the DNA way — the
+onboarding assets travel as **Kinds inside an embedded onboarding scope**
+(package-data at ``dna_cli/data/onboarding-scope/``) and are materialized
+by the SDK's own market readers/writers, not by copying text templates:
+
+  1. **Board** — creates ``.dna/<scope>/`` with a Genome written through
+     ``kernel.write_document`` (the same scope-bootstrap ``dna install``
+     performs; every write guard runs).
+  2. **Skill** — reads the embedded ``skills/dna-sdlc-cli`` bundle with the
+     ``agentskills-skill`` reader ONCE and projects it with the
+     byte-faithful SkillWriter into the skill directory of each selected
+     tool (``--tools``). The agentskills.io SKILL.md format is identical
+     across ~40 tools — only the directory differs (see ``TOOL_SKILL_DIRS``);
+     the Kind is the source of truth, the projections are regenerable.
+  3. **AGENTS.md** — the CANONICAL instruction surface (agents.md/v1 —
+     Linux Foundation stewardship, 28+ tools read it, Claude Code
+     included): read with the ``agentsmd-agent`` reader, written to the
+     project root with the AgentDefinitionWriter (the generated file
+     parses back with the same reader — market fidelity on the front
+     door). No per-tool instruction files are generated; a thin
+     CLAUDE.md/GEMINI.md pointer is the user's optional call.
+  4. **Git hooks** — wires ``core.hooksPath`` at the repo's versioned
+     hooks dir (same semantics as ``dna sdlc hooks install``); skipped
+     with a note when the directory is not a git repository.
+
+Design evidence: Research/rsh-cross-tool-agent-standards (dna-development
+board) — the cross-tool adoption facts behind the multi-tool projection.
+
+Idempotent by default: an existing file is never overwritten without
+``--force``, and the summary says exactly what was created vs skipped.
+"""
+from __future__ import annotations
+
+import asyncio
+import re
+import stat
+from importlib.resources import files as _pkg_files
+from pathlib import Path
+
+import click
+
+from dna_cli._ctx import build_source_from_env, fail, print_json
+
+SKILL_NAME = "dna-sdlc-cli"
+
+#: Container dirs seeded (with .gitkeep) so the fresh board is recognized by
+#: the CLI's sole-SDLC-scope autodetection (``_autodetect_sdlc_scope`` probes
+#: for these) and survives a git clone before the first Story lands.
+_BOARD_CONTAINERS = ("stories", "features", "issues")
+
+#: Tool → skill-projection directory. The agentskills.io SKILL.md FORMAT is
+#: identical across tools; only the discovery directory is tool-specific
+#: (Research/rsh-cross-tool-agent-standards). One Skill Kind, N projections.
+TOOL_SKILL_DIRS: dict[str, str] = {
+    "claude": ".claude/skills",
+    "copilot": ".github/skills",
+    "cursor": ".cursor/skills",
+    "opencode": ".opencode/skills",
+}
+
+#: Sensible default: Claude Code + GitHub Copilot cover the two biggest
+#: agent populations; the rest are one ``--tools`` flag away.
+DEFAULT_TOOLS = ("claude", "copilot")
+
+
+def _parse_tools(value: str) -> list[str]:
+    """Parse ``--tools`` into a validated, order-preserving tool list."""
+    if value.strip().lower() == "all":
+        return list(TOOL_SKILL_DIRS)
+    tools: list[str] = []
+    for part in value.split(","):
+        tool = part.strip().lower()
+        if not tool:
+            continue
+        if tool not in TOOL_SKILL_DIRS:
+            raise fail(
+                f"--tools: unknown tool {tool!r} — pick from "
+                f"{', '.join(TOOL_SKILL_DIRS)} (or 'all')"
+            )
+        if tool not in tools:
+            tools.append(tool)
+    if not tools:
+        raise fail("--tools: no tools selected")
+    return tools
+
+#: Step outcome labels used in the summary + --json payload.
+_CREATED = "created"
+_SKIPPED = "skipped"
+
+
+def _onboarding_root() -> Path:
+    """Root of the embedded onboarding scope shipped as package-data."""
+    return Path(str(_pkg_files("dna_cli").joinpath("data/onboarding-scope")))
+
+
+def _derive_scope(target: Path) -> str:
+    """Default board-scope name: ``<dirname>-dev``, slugified.
+
+    Follows the pilot precedent (repo ``foundry-assured`` → board scope
+    ``foundry-dev``): the board is the *dev-time* SDLC scope, distinct
+    from any runtime prompt scope the project may later add.
+    """
+    base = re.sub(r"[^a-z0-9]+", "-", target.resolve().name.lower()).strip("-")
+    base = base or "project"
+    return base if base.endswith("-dev") else f"{base}-dev"
+
+
+def _board_exists(target: Path, scope: str) -> bool:
+    """Same dual-marker contract as ``dna install`` / ``dna scope detect``."""
+    scope_dir = target / ".dna" / scope
+    return (scope_dir / "Genome.yaml").exists() or (scope_dir / "manifest.yaml").exists()
+
+
+async def _bootstrap_board(target: Path, scope: str) -> None:
+    """Create ``.dna/<scope>/`` with a Genome, written through the kernel.
+
+    Mirrors the scope-bootstrap in ``install_cmd`` ("a scope is born from
+    its Genome"): a full ``Kernel.auto()`` boot + ``write_document``, so
+    schema validation and every write guard run — never a hand-rolled YAML
+    dump. The source is pinned to ``<target>/.dna`` explicitly (NOT the
+    ambient ``DNA_SOURCE_URL``), because ``--dir`` names the project being
+    initialized, wherever the caller's env points.
+    """
+    from dna.kernel import Kernel
+
+    kernel = Kernel.auto()
+    source = await build_source_from_env(
+        kernel, _source_url=f"file://{(target / '.dna').resolve()}"
+    )
+    kernel.source(source)
+    await kernel.write_document(scope, "Genome", scope, {
+        "apiVersion": "github.com/ruinosus/dna/v1",
+        "kind": "Genome",
+        "metadata": {
+            "name": scope,
+            "description": (
+                f"Dev-time SDLC board for {target.resolve().name} — "
+                f"Features/Stories/Issues tracked via `dna sdlc`. "
+                f"Created by `dna init`."
+            ),
+        },
+        "spec": {},
+    })
+    # Seed the SDLC containers: `dna sdlc` autodetects the sole scope that
+    # HAS them (adopter boards have arbitrary names — i-012), and a fresh
+    # board must be detectable before its first Story. .gitkeep makes the
+    # empty dirs survive a git clone.
+    scope_dir = target / ".dna" / scope
+    for container in _BOARD_CONTAINERS:
+        d = scope_dir / container
+        d.mkdir(parents=True, exist_ok=True)
+        (d / ".gitkeep").touch()
+
+
+def _materialize_skills(
+    target: Path, force: bool, tools: list[str],
+) -> list[tuple[str, str, str]]:
+    """Skill Kind → one projection per selected tool, via reader→writer.
+
+    The embedded bundle is parsed ONCE with the registered
+    ``agentskills-skill`` reader and re-emitted with the byte-faithful
+    SkillWriter into each tool's skill directory — the same round-trip
+    machinery the market-conformance suites enforce. Returns one
+    ``(step, outcome, relative path)`` per tool.
+    """
+    from dna.extensions.agentskills import SkillReader, SkillWriter
+    from dna.kernel.bundle_handle import FilesystemBundleHandle
+
+    raw = SkillReader().read(
+        FilesystemBundleHandle(_onboarding_root() / "skills" / SKILL_NAME)
+    )
+    writer = SkillWriter()
+    results: list[tuple[str, str, str]] = []
+    for tool in tools:
+        rel = f"{TOOL_SKILL_DIRS[tool]}/{SKILL_NAME}"
+        dest = target / TOOL_SKILL_DIRS[tool] / SKILL_NAME
+        if (dest / "SKILL.md").exists() and not force:
+            results.append((f"skill[{tool}]", _SKIPPED, rel))
+            continue
+        dest.mkdir(parents=True, exist_ok=True)
+        writer.write(FilesystemBundleHandle(dest), raw)
+        results.append((f"skill[{tool}]", _CREATED, rel))
+    return results
+
+
+def _materialize_agents_md(target: Path, force: bool) -> tuple[str, str]:
+    """AgentDefinition Kind → ``<target>/AGENTS.md`` via reader→writer."""
+    from dna.extensions.agentsmd import AgentDefinitionReader, AgentDefinitionWriter
+    from dna.kernel.bundle_handle import FilesystemBundleHandle
+
+    if (target / "AGENTS.md").exists() and not force:
+        return _SKIPPED, "AGENTS.md"
+    raw = AgentDefinitionReader().read(FilesystemBundleHandle(_onboarding_root()))
+    AgentDefinitionWriter().write(FilesystemBundleHandle(target), raw)
+    return _CREATED, "AGENTS.md"
+
+
+def _install_hooks(target: Path) -> tuple[str, str]:
+    """Wire the git↔SDLC hook — same semantics as ``dna sdlc hooks install``,
+    with an explicit ``cwd`` (``--dir`` may not be the CWD) and skip-with-note
+    instead of hard failure, so ``dna init`` degrades gracefully in a dir
+    that is not (yet) a git repository. Returns ``(outcome, detail)``.
+    """
+    from dna_cli import _git_symbiosis as gs
+
+    root = gs.repo_root(cwd=target)
+    if root is None:
+        return _SKIPPED, "not a git repository — run `git init`, then `dna sdlc hooks install`"
+    current_raw = gs._run_git(["config", "--get", "core.hooksPath"], cwd=root)
+    current = (current_raw or "").strip() or None
+    if current not in (None, gs.HOOKS_DIR):
+        return _SKIPPED, (
+            f"core.hooksPath already set to '{current}' — merge your hooks into "
+            f"{gs.HOOKS_DIR}/ and run `dna sdlc hooks install`"
+        )
+    # Materialize the versioned hook from the packaged copy when absent
+    # (same file `dna sdlc hooks install` ensures).
+    hook = root / gs.HOOKS_DIR / gs.HOOK_NAME
+    if not hook.exists():
+        hook.parent.mkdir(parents=True, exist_ok=True)
+        hook.write_bytes(gs.hook_source_path().read_bytes())
+    mode = hook.stat().st_mode
+    if not mode & stat.S_IXUSR:
+        hook.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    if current is None:
+        if gs._run_git(["config", "core.hooksPath", gs.HOOKS_DIR], cwd=root) is None:
+            return _SKIPPED, "git config core.hooksPath failed"
+        return _CREATED, f"core.hooksPath = {gs.HOOKS_DIR}"
+    return _SKIPPED, f"already wired (core.hooksPath = {gs.HOOKS_DIR})"
+
+
+@click.command("init")
+@click.option(
+    "--scope", "scope_opt", default=None,
+    help="Board scope name (default: '<dirname>-dev', slugified — the "
+         "pilot convention for a dev-time SDLC board).",
+)
+@click.option(
+    "--dir", "dir_opt", default=".",
+    help="Project directory to initialize (default: current directory).",
+)
+@click.option(
+    "--tools", "tools_opt", default=",".join(DEFAULT_TOOLS), show_default=True,
+    help="Comma-separated agent tools to project the SDLC skill for "
+         f"({', '.join(TOOL_SKILL_DIRS)} — or 'all'). The SKILL.md format "
+         "is identical across tools; only the directory differs.",
+)
+@click.option(
+    "--force", is_flag=True,
+    help="Overwrite existing onboarding files (skill projections, "
+         "AGENTS.md). The board Genome is never rewritten — an existing "
+         "board is verified and kept.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable summary.")
+def init(scope_opt: str | None, dir_opt: str, tools_opt: str,
+         force: bool, as_json: bool) -> None:
+    """Make a project agent-ready: board + skill + AGENTS.md + git hooks.
+
+    One command bootstraps everything an AI coding agent needs to work
+    DNA-style in this project:
+
+    \b
+      .dna/<scope>/               SDLC board (Genome via the kernel)
+      <tool>/skills/dna-sdlc-cli/ the SDLC workflow skill (agentskills.io),
+                                  projected per --tools (.claude/skills,
+                                  .github/skills, .cursor/skills, ...)
+      AGENTS.md                   the canonical instruction surface
+                                  (agents.md/v1 — read by 28+ agent tools)
+      git hooks                   Work-Item commit trailers
+
+    The assets ship inside dna-cli as an embedded onboarding scope of real
+    Kinds and are materialized by the SDK's own byte-faithful
+    readers/writers — one Kind, N regenerable projections. AGENTS.md serves
+    every tool at once; Gemini CLI users can point GEMINI.md at it.
+
+    Idempotent: re-running never overwrites an existing file unless
+    --force is given; the summary reports what was created vs skipped.
+
+    Examples:
+
+    \b
+      dna init                              # here, board '<dirname>-dev'
+      dna init --scope acme-dev             # explicit board scope
+      dna init --tools all                  # every supported tool dir
+      dna init --tools claude,cursor        # explicit projection set
+      dna init --dir ../other-project       # initialize another directory
+    """
+    target = Path(dir_opt)
+    if not target.is_dir():
+        raise fail(f"--dir {dir_opt!r} is not an existing directory")
+    target = target.resolve()
+    scope = scope_opt or _derive_scope(target)
+    if not re.fullmatch(r"[a-z0-9][a-z0-9-]*", scope):
+        raise fail(
+            f"--scope {scope!r} must be a slug (lowercase letters, digits, '-')"
+        )
+    tools = _parse_tools(tools_opt)
+
+    results: list[tuple[str, str, str]] = []  # (step, outcome, detail)
+
+    # 1. Board — create when missing, verify + keep when present.
+    board_rel = f".dna/{scope}"
+    if _board_exists(target, scope):
+        results.append(("board", _SKIPPED, f"{board_rel} already exists"))
+    else:
+        asyncio.run(_bootstrap_board(target, scope))
+        results.append(("board", _CREATED, board_rel))
+
+    # 2. Skill Kind → one projection per tool (byte-faithful writer).
+    results.extend(_materialize_skills(target, force, tools))
+
+    # 3. AGENTS.md (agentsmd-agent Kind) — the canonical instruction surface.
+    outcome, detail = _materialize_agents_md(target, force)
+    results.append(("agents-md", outcome, detail))
+
+    # 4. Git hooks (Work-Item trailers).
+    outcome, detail = _install_hooks(target)
+    results.append(("hooks", outcome, detail))
+
+    if as_json:
+        print_json({
+            "dir": str(target),
+            "scope": scope,
+            "steps": [
+                {"step": s, "outcome": o, "detail": d} for s, o, d in results
+            ],
+        })
+        return
+
+    click.secho(f"dna init — {target}  (board scope: {scope})", bold=True)
+    step_width = max(len(s) for s, _, _ in results)
+    for step, outcome, detail in results:
+        color = "green" if outcome == _CREATED else "yellow"
+        click.secho(f"  {outcome:<7} {step:<{step_width}} {detail}", fg=color)
+    n_created = sum(1 for _, o, _ in results if o == _CREATED)
+    n_skipped = len(results) - n_created
+    click.secho(
+        f"\n{n_created} created · {n_skipped} skipped"
+        + ("" if force or not n_skipped else "  (re-run with --force to overwrite files)"),
+        bold=True,
+    )
+    click.echo(
+        "\nNext steps:\n"
+        "  dna sdlc feature create f-my-area --title \"...\" --desc \"...\"\n"
+        "  dna sdlc story create s-my-first-story --feature f-my-area --desc \"...\" \\\n"
+        "    --ac \"Given/When/Then ...\" --dod \"code+tests+docs\"\n"
+        "  dna sdlc story start s-my-first-story --plan \"plan of attack\"\n"
+        f"  (your agent: read AGENTS.md + the {SKILL_NAME} skill in its "
+        f"tool's skills dir)"
+    )