specthis 0.0.1__tar.gz

specthis-0.0.1/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+      - run: ruff check src tests

specthis-0.0.1/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.ruff_cache/
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+
+# Local config
+.env
+.envrc
+
+# specthis dev artefacts
+/tmp_specs/
+*.local.toml

specthis-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thibaut Lamadon
+
+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.

specthis-0.0.1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: specthis
+Version: 0.0.1
+Summary: Spec-driven research workflow: a dashboard, Claude Code subagents, and a refresh/cache pipeline for reproducible compute + LaTeX reports.
+Project-URL: Homepage, https://github.com/tlamadon/specthis
+Project-URL: Repository, https://github.com/tlamadon/specthis
+Project-URL: Issues, https://github.com/tlamadon/specthis/issues
+Author: Thibaut Lamadon
+License: MIT
+License-File: LICENSE
+Keywords: claude-code,latex,reproducibility,research,specs,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: markdown>=3.5
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.28; extra == 's3'
+Provides-Extra: serve
+Requires-Dist: starlette>=0.36; extra == 'serve'
+Requires-Dist: uvicorn>=0.27; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# specthis
+
+A spec-driven research workflow: a dashboard, Claude Code subagents, and
+a refresh/cache pipeline for projects that produce reproducible compute
+artefacts (typically JSON) and assemble them into a LaTeX (or similar)
+report.
+
+> Status: **early scaffold**. The CLI shell and the agent / spec
+> templates work. The dashboard renderer, lock manager, S3 cache, and
+> refresh orchestrator are stubs awaiting porting from the reference
+> implementation. See [Roadmap](#roadmap).
+
+## What it is
+
+A small package that gives a research project:
+
+1. **A spec format.** Each `compute-*.md` / `report-*.md` file in
+   `specs/` declares the path of a script that produces a JSON
+   artefact (compute) or a LaTeX figure / table (report), plus a
+   `Status:` line that pins whether the script satisfies the
+   contract.
+2. **A dashboard.** `specs/specs.html` renders the directory as a
+   browsable view of entries, their statuses, the produced
+   artefacts, and the cross-references between compute outputs and
+   report inputs.
+3. **A content-hash lock.** `specs/_lock.json` records the hash of
+   each entry's spec + script content at the moment it was certified
+   `script ready`. The refresh orchestrator refuses to rerun an
+   entry whose spec or script has drifted from the certified hash
+   without an explicit re-audit.
+4. **Three Claude Code subagents.** Drop-in agents for the three
+   operations a human or LLM does daily on a spec directory:
+   - `spec-auditor` — read-only consistency check (operation 1).
+   - `spec-implementer` — author a missing script for a
+     `script TBD` entry (operation 3).
+   - `experiment-runner` — kick off a long-running script in the
+     background, monitor its log for milestones / errors, report
+     completion.
+5. **(Optional) An S3 compute cache.** Push the `results/<entry>/`
+   directory to S3 keyed by the spec's `inputs_certified` hash, so
+   collaborators can pull instead of re-running.
+
+## Install
+
+```bash
+pip install specthis        # core: CLI + agent templates
+pip install "specthis[s3]"  # adds the S3 cache backend
+```
+
+## Scaffold a project
+
+In any project directory:
+
+```bash
+specthis install            # writes the three agents into .claude/agents/
+specthis init               # creates specs/ with README.md + AGENTS.md templates
+```
+
+After `init`, edit `specs/README.md` and add your first
+`compute-<name>.md` / `report-<name>.md` pair.
+
+## CLI
+
+```
+specthis install    Copy agent templates into <cwd>/.claude/agents/
+specthis init       Create specs/ skeleton (README.md + AGENTS.md)
+specthis audit      Run the consistency audit (stub — port pending)
+specthis refresh    Rerun stale entries respecting the lock (stub — port pending)
+specthis serve      Start a local dev server for specs.html (stub — port pending)
+specthis lock       Manage the content-hash lock file (stub — port pending)
+```
+
+## The spec format in one paragraph
+
+Every spec file under `specs/` carries YAML frontmatter
+(`name`, `kind`, `depends_on`) and one of two body shapes:
+
+- **`kind: compute`** — a `## Script` prose section describing how
+  the script is laid out, plus one or more `### entry-name` blocks
+  each carrying `Script:`, `Output:` (a JSON path), and `Status:`.
+- **`kind: report`** — same shape, but per-entry fields are
+  `Export script:`, `Export outputs:` (LaTeX paths), and `Status:`,
+  plus frontmatter `host_doc:` and `section_label:` that route the
+  artefacts into a section of a top-level `.tex` document.
+
+`Status:` is `script TBD` (the script does not satisfy the contract)
+or `script ready` (it does, and a smoke-test passed). The
+`scripts ran` vs `outputs exist on disk` axis is observed by the
+auditor and the dashboard — it is not part of the spec.
+
+See `src/specthis/templates/specs/README.md` for the full convention.
+
+## Roadmap
+
+The reference implementation (a ~7000 LOC private codebase) is being
+ported into this package one module at a time. Order:
+
+1. **agent templates + spec format docs** — done (this scaffold).
+2. **`specthis install` / `specthis init`** — done.
+3. **`specthis audit`** — port the index-based auditor.
+4. **`specthis serve`** — port the HTML dashboard renderer +
+   `_index.json` / `_routing.json` exporter.
+5. **`specthis lock`** — port the content-hash lock manager.
+6. **`specthis refresh`** — port the Makefile-driven refresh
+   orchestrator.
+7. **`specthis cache`** — port the S3 backend.
+
+Each module ships with a config-driven surface (paths configurable
+via `specthis.toml`), no hard-coded assumptions about the host
+project's layout beyond the defaults documented in the spec format.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

specthis-0.0.1/README.md

@@ -0,0 +1,114 @@
+# specthis
+
+A spec-driven research workflow: a dashboard, Claude Code subagents, and
+a refresh/cache pipeline for projects that produce reproducible compute
+artefacts (typically JSON) and assemble them into a LaTeX (or similar)
+report.
+
+> Status: **early scaffold**. The CLI shell and the agent / spec
+> templates work. The dashboard renderer, lock manager, S3 cache, and
+> refresh orchestrator are stubs awaiting porting from the reference
+> implementation. See [Roadmap](#roadmap).
+
+## What it is
+
+A small package that gives a research project:
+
+1. **A spec format.** Each `compute-*.md` / `report-*.md` file in
+   `specs/` declares the path of a script that produces a JSON
+   artefact (compute) or a LaTeX figure / table (report), plus a
+   `Status:` line that pins whether the script satisfies the
+   contract.
+2. **A dashboard.** `specs/specs.html` renders the directory as a
+   browsable view of entries, their statuses, the produced
+   artefacts, and the cross-references between compute outputs and
+   report inputs.
+3. **A content-hash lock.** `specs/_lock.json` records the hash of
+   each entry's spec + script content at the moment it was certified
+   `script ready`. The refresh orchestrator refuses to rerun an
+   entry whose spec or script has drifted from the certified hash
+   without an explicit re-audit.
+4. **Three Claude Code subagents.** Drop-in agents for the three
+   operations a human or LLM does daily on a spec directory:
+   - `spec-auditor` — read-only consistency check (operation 1).
+   - `spec-implementer` — author a missing script for a
+     `script TBD` entry (operation 3).
+   - `experiment-runner` — kick off a long-running script in the
+     background, monitor its log for milestones / errors, report
+     completion.
+5. **(Optional) An S3 compute cache.** Push the `results/<entry>/`
+   directory to S3 keyed by the spec's `inputs_certified` hash, so
+   collaborators can pull instead of re-running.
+
+## Install
+
+```bash
+pip install specthis        # core: CLI + agent templates
+pip install "specthis[s3]"  # adds the S3 cache backend
+```
+
+## Scaffold a project
+
+In any project directory:
+
+```bash
+specthis install            # writes the three agents into .claude/agents/
+specthis init               # creates specs/ with README.md + AGENTS.md templates
+```
+
+After `init`, edit `specs/README.md` and add your first
+`compute-<name>.md` / `report-<name>.md` pair.
+
+## CLI
+
+```
+specthis install    Copy agent templates into <cwd>/.claude/agents/
+specthis init       Create specs/ skeleton (README.md + AGENTS.md)
+specthis audit      Run the consistency audit (stub — port pending)
+specthis refresh    Rerun stale entries respecting the lock (stub — port pending)
+specthis serve      Start a local dev server for specs.html (stub — port pending)
+specthis lock       Manage the content-hash lock file (stub — port pending)
+```
+
+## The spec format in one paragraph
+
+Every spec file under `specs/` carries YAML frontmatter
+(`name`, `kind`, `depends_on`) and one of two body shapes:
+
+- **`kind: compute`** — a `## Script` prose section describing how
+  the script is laid out, plus one or more `### entry-name` blocks
+  each carrying `Script:`, `Output:` (a JSON path), and `Status:`.
+- **`kind: report`** — same shape, but per-entry fields are
+  `Export script:`, `Export outputs:` (LaTeX paths), and `Status:`,
+  plus frontmatter `host_doc:` and `section_label:` that route the
+  artefacts into a section of a top-level `.tex` document.
+
+`Status:` is `script TBD` (the script does not satisfy the contract)
+or `script ready` (it does, and a smoke-test passed). The
+`scripts ran` vs `outputs exist on disk` axis is observed by the
+auditor and the dashboard — it is not part of the spec.
+
+See `src/specthis/templates/specs/README.md` for the full convention.
+
+## Roadmap
+
+The reference implementation (a ~7000 LOC private codebase) is being
+ported into this package one module at a time. Order:
+
+1. **agent templates + spec format docs** — done (this scaffold).
+2. **`specthis install` / `specthis init`** — done.
+3. **`specthis audit`** — port the index-based auditor.
+4. **`specthis serve`** — port the HTML dashboard renderer +
+   `_index.json` / `_routing.json` exporter.
+5. **`specthis lock`** — port the content-hash lock manager.
+6. **`specthis refresh`** — port the Makefile-driven refresh
+   orchestrator.
+7. **`specthis cache`** — port the S3 backend.
+
+Each module ships with a config-driven surface (paths configurable
+via `specthis.toml`), no hard-coded assumptions about the host
+project's layout beyond the defaults documented in the spec format.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

specthis-0.0.1/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "specthis"
+version = "0.0.1"
+description = "Spec-driven research workflow: a dashboard, Claude Code subagents, and a refresh/cache pipeline for reproducible compute + LaTeX reports."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Thibaut Lamadon" },
+]
+keywords = ["specs", "research", "reproducibility", "claude-code", "latex", "workflow"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "click>=8.1",
+    "pyyaml>=6.0",
+    "markdown>=3.5",
+]
+
+[project.optional-dependencies]
+s3 = ["boto3>=1.28"]
+serve = ["uvicorn>=0.27", "starlette>=0.36"]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "ruff>=0.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/tlamadon/specthis"
+Repository = "https://github.com/tlamadon/specthis"
+Issues = "https://github.com/tlamadon/specthis/issues"
+
+[project.scripts]
+specthis = "specthis.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/specthis"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

specthis-0.0.1/src/specthis/__init__.py

@@ -0,0 +1,3 @@
+"""specthis — spec-driven research workflow tooling."""
+
+__version__ = "0.0.1"

specthis-0.0.1/src/specthis/audit.py

@@ -0,0 +1,29 @@
+"""Spec consistency audit (operation 1 from specs/AGENTS.md).
+
+Status: **stub**. The reference implementation is index-based: it
+reads ``specs/_index.json`` and ``specs/_routing.json`` (produced by
+:mod:`specthis.export`) and reports each entry's script existence,
+contract-in-spirit, output schema, export routing, and freshness in a
+single markdown table.
+
+Port plan:
+- ``walk_index(specs_dir) -> list[EntryReport]``
+- ``check_compute_entry(entry, index) -> EntryReport``
+- ``check_report_entry(entry, index, routing) -> EntryReport``
+- ``format_table(reports) -> str``
+
+Until ported, invoke the bundled ``spec-auditor`` subagent in Claude
+Code instead — it implements the same checks by reading the index
+files directly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def run_audit(specs_dir: Path) -> str:  # pragma: no cover - stub
+    raise NotImplementedError(
+        "specthis.audit is not yet ported. Use the spec-auditor subagent "
+        "(installed by `specthis install`) in the meantime."
+    )

specthis-0.0.1/src/specthis/cache.py

@@ -0,0 +1,26 @@
+"""S3-backed compute cache for spec entries.
+
+Status: **stub**. The reference implementation provides four
+operations keyed by an entry's ``inputs_certified`` hash:
+
+- ``push <entry>``: tar the entry's ``results/<entry>/`` directory and
+  upload to ``s3://<bucket>/cache/<input_sig>/<entry>.tar.gz``.
+- ``fetch <entry>``: download and unpack into ``results/<entry>/``.
+- ``has <entry>``: HEAD-check S3 for the artefact.
+- ``list``: list cached entries with their input signatures.
+
+Requires ``specthis[s3]`` extra (boto3) and AWS credentials available
+in the standard chain (env, profile, instance role).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def push(entry: str, bucket: str, specs_dir: Path) -> None:  # pragma: no cover - stub
+    raise NotImplementedError("specthis.cache is not yet ported.")
+
+
+def fetch(entry: str, bucket: str, specs_dir: Path) -> None:  # pragma: no cover - stub
+    raise NotImplementedError("specthis.cache is not yet ported.")

specthis-0.0.1/src/specthis/cli.py

@@ -0,0 +1,132 @@
+"""specthis command-line entry point."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .install import install_agents, init_specs_dir
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="specthis")
+def main() -> None:
+    """Spec-driven research workflow: dashboard, agents, refresh pipeline."""
+
+
+@main.command("install")
+@click.option(
+    "--path",
+    "project_path",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=Path.cwd(),
+    show_default="current directory",
+    help="Project root in which to install .claude/agents/.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Overwrite existing agent files.",
+)
+@click.option(
+    "--agent",
+    "selected",
+    multiple=True,
+    type=click.Choice(["spec-auditor", "spec-implementer", "experiment-runner"]),
+    help="Install only the named agent(s). Repeatable. Default: all three.",
+)
+def install_cmd(project_path: Path, force: bool, selected: tuple[str, ...]) -> None:
+    """Copy the specthis subagent templates into <project>/.claude/agents/."""
+    installed, skipped = install_agents(
+        project_path=project_path,
+        force=force,
+        agents=list(selected) if selected else None,
+    )
+    for name in installed:
+        click.echo(f"  installed  {name}")
+    for name, reason in skipped:
+        click.echo(f"  skipped    {name}  ({reason})", err=True)
+    if not installed and skipped:
+        click.echo("\nNothing changed. Re-run with --force to overwrite.", err=True)
+        sys.exit(1)
+
+
+@main.command("init")
+@click.option(
+    "--path",
+    "project_path",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=Path.cwd(),
+    show_default="current directory",
+    help="Project root in which to create specs/.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Overwrite existing template files in specs/.",
+)
+def init_cmd(project_path: Path, force: bool) -> None:
+    """Create specs/ with README.md and AGENTS.md spec-format templates."""
+    created, skipped = init_specs_dir(project_path=project_path, force=force)
+    for path in created:
+        click.echo(f"  created    {path}")
+    for path, reason in skipped:
+        click.echo(f"  skipped    {path}  ({reason})", err=True)
+
+
+@main.command("audit")
+@click.option(
+    "--specs",
+    "specs_dir",
+    type=click.Path(file_okay=False, exists=True, path_type=Path),
+    default=Path("specs"),
+    show_default=True,
+    help="specs/ directory to audit.",
+)
+def audit_cmd(specs_dir: Path) -> None:
+    """Run the consistency audit over specs/. (stub — port pending)"""
+    click.echo(
+        f"specthis audit: not yet implemented. Would audit {specs_dir}.\n"
+        "Until then, invoke the spec-auditor subagent in Claude Code.",
+        err=True,
+    )
+    sys.exit(2)
+
+
+@main.command("refresh")
+@click.option(
+    "--specs",
+    "specs_dir",
+    type=click.Path(file_okay=False, exists=True, path_type=Path),
+    default=Path("specs"),
+    show_default=True,
+)
+def refresh_cmd(specs_dir: Path) -> None:
+    """Re-run stale entries respecting the lock file. (stub — port pending)"""
+    click.echo("specthis refresh: not yet implemented.", err=True)
+    sys.exit(2)
+
+
+@main.command("serve")
+@click.option("--host", default="127.0.0.1", show_default=True)
+@click.option("--port", type=int, default=8765, show_default=True)
+def serve_cmd(host: str, port: int) -> None:
+    """Serve the specs.html dashboard with live reload. (stub — port pending)"""
+    click.echo("specthis serve: not yet implemented.", err=True)
+    sys.exit(2)
+
+
+@main.command("lock")
+@click.argument("subcommand", type=click.Choice(["status", "record", "clear"]))
+@click.argument("entry", required=False)
+def lock_cmd(subcommand: str, entry: str | None) -> None:
+    """Manage the spec inputs_certified content-hash lock. (stub — port pending)"""
+    click.echo(f"specthis lock {subcommand}: not yet implemented.", err=True)
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

specthis-0.0.1/src/specthis/export.py

@@ -0,0 +1,30 @@
+"""Dashboard renderer: builds specs/specs.html + _index.json + _routing.json.
+
+Status: **stub**. The reference implementation walks ``specs/*.md``,
+parses each frontmatter + entry block, joins against the working tree
+(script existence, output existence + top-level keys, export
+artefacts, host-doc routing), and emits three artefacts:
+
+- ``specs/specs.html`` — a single-file browsable dashboard of every
+  spec, entry, and pairing.
+- ``specs/_index.json`` — per-spec frontmatter + per-entry facts,
+  consumed by :mod:`specthis.audit` and the auditor subagent.
+- ``specs/_routing.json`` — per host-doc, per label section, the
+  ``\\input{}`` / ``\\includegraphics{}`` lines found inside, plus
+  ``\\sectionversion`` proximity flags.
+
+Port plan:
+- ``parse_spec(path) -> SpecFile``
+- ``join_against_worktree(specs, project_root) -> IndexData``
+- ``walk_host_docs(reports_dir) -> RoutingData``
+- ``render_html(index, routing) -> str``
+- ``write_artefacts(specs_dir, index, routing, html) -> None``
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def render(specs_dir: Path, project_root: Path) -> None:  # pragma: no cover - stub
+    raise NotImplementedError("specthis.export is not yet ported.")

specthis-0.0.1/src/specthis/install.py

@@ -0,0 +1,69 @@
+"""Scaffolder: copy bundled templates into a project directory."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+AGENT_NAMES = ("spec-auditor", "spec-implementer", "experiment-runner")
+SPEC_TEMPLATE_NAMES = ("README.md", "AGENTS.md")
+
+
+def _read_template(subdir: str, filename: str) -> str:
+    """Read a bundled template file from the installed package."""
+    package = f"specthis.templates.{subdir}"
+    return resources.files(package).joinpath(filename).read_text(encoding="utf-8")
+
+
+def install_agents(
+    project_path: Path,
+    force: bool = False,
+    agents: list[str] | None = None,
+) -> tuple[list[str], list[tuple[str, str]]]:
+    """Copy agent templates into ``<project_path>/.claude/agents/``.
+
+    Returns ``(installed, skipped)`` where ``installed`` is a list of agent
+    names written and ``skipped`` is a list of ``(name, reason)``.
+    """
+    selected = agents or list(AGENT_NAMES)
+    target_dir = project_path / ".claude" / "agents"
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    installed: list[str] = []
+    skipped: list[tuple[str, str]] = []
+    for name in selected:
+        if name not in AGENT_NAMES:
+            skipped.append((name, "unknown agent"))
+            continue
+        target = target_dir / f"{name}.md"
+        if target.exists() and not force:
+            skipped.append((name, "already exists; use --force"))
+            continue
+        body = _read_template("agents", f"{name}.md")
+        target.write_text(body, encoding="utf-8")
+        installed.append(name)
+    return installed, skipped
+
+
+def init_specs_dir(
+    project_path: Path,
+    force: bool = False,
+) -> tuple[list[Path], list[tuple[Path, str]]]:
+    """Create ``<project_path>/specs/`` with the README and AGENTS templates.
+
+    Returns ``(created, skipped)``.
+    """
+    target_dir = project_path / "specs"
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    created: list[Path] = []
+    skipped: list[tuple[Path, str]] = []
+    for filename in SPEC_TEMPLATE_NAMES:
+        target = target_dir / filename
+        if target.exists() and not force:
+            skipped.append((target, "already exists; use --force"))
+            continue
+        body = _read_template("specs", filename)
+        target.write_text(body, encoding="utf-8")
+        created.append(target)
+    return created, skipped