specced 0.1.0__tar.gz

specced-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Claude Code session-local settings (per-user, not shared)
+.claude/settings.local.json
+
+# specced never ignores its own templates; target repos manage their own .specced/

specced-0.1.0/LICENSE

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

specced-0.1.0/NOTICE

@@ -0,0 +1,20 @@
+specced
+Copyright (c) 2026 Norik Saroyan
+Licensed under the MIT License (see LICENSE).
+
+================================================================================
+Bundled third-party components
+================================================================================
+
+This distribution vendors the "repo-task-proof-loop" skill, which is the
+proof-loop engine specced installs into target repositories.
+
+  Component: repo-task-proof-loop
+  Author:    OpenAI
+  License:   Apache License 2.0
+  Location:  src/specced/templates/skills/repo-task-proof-loop/
+  License text: src/specced/templates/skills/repo-task-proof-loop/LICENSE
+
+The component is redistributed unmodified under the terms of the Apache License
+2.0. specced layers its own scaffolding (rules, code-review, constitution, MCP,
+Makefile vocabulary, and the bootstrap interview) around it; that layer is MIT.

specced-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: specced
+Version: 0.1.0
+Summary: Interview-driven bootstrap for a reusable agentic coding setup: proof-loop engine + project rules + skills, installed into any repo.
+Project-URL: Homepage, https://github.com/NoroSaroyan/specced
+Project-URL: Issues, https://github.com/NoroSaroyan/specced/issues
+Author-email: Norik Saroyan <noriksaroyan@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Norik Saroyan
+        
+        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.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agentic,claude-code,codex,coding-agent,proof-loop,scaffold,spec-driven
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# specced
+
+Install a reusable, **interview-driven agentic coding setup** into any repo — one
+command instead of copy-pasting `.claude/`, `.codex/`, `CONSTITUTION.md`, and the
+proof-loop scaffolding between projects.
+
+specced is two things sharing one set of templates:
+
+- a **uv-installable CLI** that does the deterministic, agent-agnostic scaffolding, and
+- a **Claude Code plugin** whose `specced-bootstrap` skill *interviews you* — detects
+  your stack, asks a few sharp questions, and writes the project-specific content.
+
+## What you get
+
+specced installs three layers into a repo:
+
+1. **The engine** — the [`repo-task-proof-loop`](src/specced/templates/skills/repo-task-proof-loop)
+   skill (spec-freeze → build → evidence → fresh-verify → fix, with durable
+   `.agent/tasks/<ID>/` artifacts). Vendored from OpenAI, Apache-2.0 — see [NOTICE](NOTICE).
+2. **The structure** — four project agents (`.claude/agents/` + `.codex/agents/`),
+   managed blocks in `CLAUDE.md`/`AGENTS.md`, a Stop-hook formatter, skeletons for
+   `.claude/rules/`, `.claude/code-review/`, `.mcp.json`, and a `Makefile` verification
+   vocabulary — plus an **agent-experience layer**: a pre-authorized permission
+   allowlist, an orientation block, and a machine-readable checks map (`.specced/`).
+3. **The content** *(interview)* — your real `CONSTITUTION.md`, per-track rules,
+   review dimensions, MCP servers, and `make` targets — authored to fit *this* repo.
+
+## Install
+
+```bash
+uv tool install specced          # or: uvx --from git+https://github.com/NoroSaroyan/specced specced
+```
+
+In Claude Code, add the marketplace and install the plugin:
+
+```
+/plugin marketplace add NoroSaroyan/specced
+/plugin install specced
+```
+
+## Quickstart
+
+From inside the target repo, in Claude Code:
+
+```
+/specced:init
+```
+
+This runs the interview: it detects your stack, asks what matters, runs
+`specced init` for the mechanics, then writes your constitution, rules, review
+dimensions, MCP servers, and Makefile targets. Add `--minimal` to author all
+content by hand.
+
+Then start your first task with the installed engine:
+
+```
+init my-first-task     # via the repo-task-proof-loop skill
+```
+
+## Documentation
+
+Full docs in [`docs/`](docs/index.md):
+[Getting started](docs/getting-started.md) ·
+[Concepts](docs/concepts.md) ·
+[The proof loop](docs/proof-loop.md) ·
+[CLI reference](docs/cli-reference.md) ·
+[Skills](docs/skills.md) ·
+[Presets](docs/presets.md) ·
+[FAQ](docs/faq.md)
+
+## CLI reference
+
+```
+specced detect                    Inspect the repo: languages, tracks, infra,
+                                  suggested preset + MCP servers (JSON).
+specced presets                   List stack presets.
+specced init [--preset NAME|auto] [--minimal] [--force] [--format-cmd "…"]
+                                  Install / refresh the setup (idempotent).
+specced add-mcp <names…> [--force]  Add MCP servers to .mcp.json from the catalog.
+specced add-skill <name> [--force]  Install a library skill into .claude/skills/.
+specced list-skills               List available library skills.
+specced sync                      Refresh engine + agents + managed blocks.
+specced doctor                    Verify the setup is consistent.
+specced status                    Show installed components, presets, mcp catalog, config.
+specced version                   Print specced + engine versions.
+```
+
+**12 presets** (`go`, `rust`, `python-fastapi`, `python-django`, `python`,
+`node-next`, `node-svelte`, `node-react`, `node-express`, `node`, `java-spring`,
+`ruby-rails` — see [docs/presets.md](docs/presets.md)) and a **17-skill library**
+(code-review, api-endpoint, db-migration, add-integration, background-worker,
+regen-client, write-tests, debug-issue, refactor, dependency-upgrade,
+perf-investigation, security-review, release, prepare-pr, new-domain-skill,
+decision-record, capture-rule — see [docs/skills.md](docs/skills.md)).
+
+Every command prints JSON, so the interview agent can read exactly what happened.
+State is recorded in `.specced/config.json`.
+
+## How it works
+
+The CLI is the mechanical half: it copies the vendored engine, installs the static
+agent + managed-block templates verbatim (the same files the engine itself would
+write), and lays down create-if-absent skeletons for the content layer. The plugin
+is the intelligent half: the `specced-bootstrap` skill detects, interviews, calls
+the CLI, then replaces the skeletons with real content. One template tree, two
+surfaces.
+
+## Develop
+
+```bash
+make install   # uv venv + editable install with dev extras
+make verify    # ruff format --check + ruff check + pytest + build (the CI gate)
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/architecture.md](docs/architecture.md).
+
+## Status
+
+v0.1 — interview-first, with stack detection, 12 presets, a 7-server MCP catalog, a
+17-skill library, an agent-experience layer, and GitHub repo-as-code (Terraform under
+`infra/terraform/github/`). Roadmap: a `specced update` that diffs managed content
+across versions, more presets/skills, and PyPI publication.
+
+## License
+
+specced is MIT (see [LICENSE](LICENSE)). It bundles the Apache-2.0
+`repo-task-proof-loop` engine unmodified; attribution in [NOTICE](NOTICE).

specced-0.1.0/README.md

@@ -0,0 +1,127 @@
+# specced
+
+Install a reusable, **interview-driven agentic coding setup** into any repo — one
+command instead of copy-pasting `.claude/`, `.codex/`, `CONSTITUTION.md`, and the
+proof-loop scaffolding between projects.
+
+specced is two things sharing one set of templates:
+
+- a **uv-installable CLI** that does the deterministic, agent-agnostic scaffolding, and
+- a **Claude Code plugin** whose `specced-bootstrap` skill *interviews you* — detects
+  your stack, asks a few sharp questions, and writes the project-specific content.
+
+## What you get
+
+specced installs three layers into a repo:
+
+1. **The engine** — the [`repo-task-proof-loop`](src/specced/templates/skills/repo-task-proof-loop)
+   skill (spec-freeze → build → evidence → fresh-verify → fix, with durable
+   `.agent/tasks/<ID>/` artifacts). Vendored from OpenAI, Apache-2.0 — see [NOTICE](NOTICE).
+2. **The structure** — four project agents (`.claude/agents/` + `.codex/agents/`),
+   managed blocks in `CLAUDE.md`/`AGENTS.md`, a Stop-hook formatter, skeletons for
+   `.claude/rules/`, `.claude/code-review/`, `.mcp.json`, and a `Makefile` verification
+   vocabulary — plus an **agent-experience layer**: a pre-authorized permission
+   allowlist, an orientation block, and a machine-readable checks map (`.specced/`).
+3. **The content** *(interview)* — your real `CONSTITUTION.md`, per-track rules,
+   review dimensions, MCP servers, and `make` targets — authored to fit *this* repo.
+
+## Install
+
+```bash
+uv tool install specced          # or: uvx --from git+https://github.com/NoroSaroyan/specced specced
+```
+
+In Claude Code, add the marketplace and install the plugin:
+
+```
+/plugin marketplace add NoroSaroyan/specced
+/plugin install specced
+```
+
+## Quickstart
+
+From inside the target repo, in Claude Code:
+
+```
+/specced:init
+```
+
+This runs the interview: it detects your stack, asks what matters, runs
+`specced init` for the mechanics, then writes your constitution, rules, review
+dimensions, MCP servers, and Makefile targets. Add `--minimal` to author all
+content by hand.
+
+Then start your first task with the installed engine:
+
+```
+init my-first-task     # via the repo-task-proof-loop skill
+```
+
+## Documentation
+
+Full docs in [`docs/`](docs/index.md):
+[Getting started](docs/getting-started.md) ·
+[Concepts](docs/concepts.md) ·
+[The proof loop](docs/proof-loop.md) ·
+[CLI reference](docs/cli-reference.md) ·
+[Skills](docs/skills.md) ·
+[Presets](docs/presets.md) ·
+[FAQ](docs/faq.md)
+
+## CLI reference
+
+```
+specced detect                    Inspect the repo: languages, tracks, infra,
+                                  suggested preset + MCP servers (JSON).
+specced presets                   List stack presets.
+specced init [--preset NAME|auto] [--minimal] [--force] [--format-cmd "…"]
+                                  Install / refresh the setup (idempotent).
+specced add-mcp <names…> [--force]  Add MCP servers to .mcp.json from the catalog.
+specced add-skill <name> [--force]  Install a library skill into .claude/skills/.
+specced list-skills               List available library skills.
+specced sync                      Refresh engine + agents + managed blocks.
+specced doctor                    Verify the setup is consistent.
+specced status                    Show installed components, presets, mcp catalog, config.
+specced version                   Print specced + engine versions.
+```
+
+**12 presets** (`go`, `rust`, `python-fastapi`, `python-django`, `python`,
+`node-next`, `node-svelte`, `node-react`, `node-express`, `node`, `java-spring`,
+`ruby-rails` — see [docs/presets.md](docs/presets.md)) and a **17-skill library**
+(code-review, api-endpoint, db-migration, add-integration, background-worker,
+regen-client, write-tests, debug-issue, refactor, dependency-upgrade,
+perf-investigation, security-review, release, prepare-pr, new-domain-skill,
+decision-record, capture-rule — see [docs/skills.md](docs/skills.md)).
+
+Every command prints JSON, so the interview agent can read exactly what happened.
+State is recorded in `.specced/config.json`.
+
+## How it works
+
+The CLI is the mechanical half: it copies the vendored engine, installs the static
+agent + managed-block templates verbatim (the same files the engine itself would
+write), and lays down create-if-absent skeletons for the content layer. The plugin
+is the intelligent half: the `specced-bootstrap` skill detects, interviews, calls
+the CLI, then replaces the skeletons with real content. One template tree, two
+surfaces.
+
+## Develop
+
+```bash
+make install   # uv venv + editable install with dev extras
+make verify    # ruff format --check + ruff check + pytest + build (the CI gate)
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/architecture.md](docs/architecture.md).
+
+## Status
+
+v0.1 — interview-first, with stack detection, 12 presets, a 7-server MCP catalog, a
+17-skill library, an agent-experience layer, and GitHub repo-as-code (Terraform under
+`infra/terraform/github/`). Roadmap: a `specced update` that diffs managed content
+across versions, more presets/skills, and PyPI publication.
+
+## License
+
+specced is MIT (see [LICENSE](LICENSE)). It bundles the Apache-2.0
+`repo-task-proof-loop` engine unmodified; attribution in [NOTICE](NOTICE).

specced-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "specced"
+version = "0.1.0"
+description = "Interview-driven bootstrap for a reusable agentic coding setup: proof-loop engine + project rules + skills, installed into any repo."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Norik Saroyan", email = "noriksaroyan@gmail.com" }]
+keywords = [
+    "claude-code",
+    "agentic",
+    "coding-agent",
+    "scaffold",
+    "proof-loop",
+    "spec-driven",
+    "codex",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Code Generators",
+]
+
+[project.scripts]
+specced = "specced.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.6", "build"]
+
+[project.urls]
+Homepage = "https://github.com/NoroSaroyan/specced"
+Issues = "https://github.com/NoroSaroyan/specced/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/specced"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/README.md", "/LICENSE", "/NOTICE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+# Never lint the bundled templates (they include the vendored engine + example code).
+extend-exclude = ["src/specced/templates"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]  # line length is owned by the formatter
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = "-q"

specced-0.1.0/src/specced/__init__.py

@@ -0,0 +1,11 @@
+"""specced — install a reusable, interview-driven agentic coding setup into any repo.
+
+The Python package is the *deterministic* half of specced: it scaffolds the
+proof-loop engine, project-scoped agents, managed guide blocks, and the
+Layer-2 structure (constitution, rules, code-review, mcp, Makefile vocabulary).
+
+The *intelligent* half — the interview that fills in project-specific content —
+lives in the Claude Code plugin under ``plugin/`` and drives this CLI.
+"""
+
+__version__ = "0.1.0"

specced-0.1.0/src/specced/_paths.py

@@ -0,0 +1,11 @@
+"""Resource-path resolution shared by scaffold and detect (avoids an import cycle)."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+
+def templates_dir() -> Path:
+    """Path to the bundled templates directory (works for editable + wheel)."""
+    return Path(str(files("specced"))) / "templates"

specced-0.1.0/src/specced/cli.py

@@ -0,0 +1,178 @@
+"""specced command-line interface.
+
+Thin wrapper over :mod:`specced.scaffold`. Every command prints a JSON result to
+stdout so the interview agent (or a human) can read exactly what happened.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+from . import scaffold
+
+
+def _repo_root(args: argparse.Namespace) -> Path:
+    start = Path(args.repo_root).resolve() if args.repo_root else Path.cwd()
+    return scaffold.discover_repo_root(start)
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, indent=2))
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    _emit(
+        scaffold.init_repo(
+            _repo_root(args),
+            minimal=args.minimal,
+            force=args.force,
+            format_cmd=args.format_cmd,
+            preset=args.preset,
+        )
+    )
+    return 0
+
+
+def cmd_detect(args: argparse.Namespace) -> int:
+    _emit(scaffold.detect_repo(_repo_root(args)))
+    return 0
+
+
+def cmd_presets(args: argparse.Namespace) -> int:
+    _emit({"presets": scaffold.list_presets()})
+    return 0
+
+
+def cmd_add_mcp(args: argparse.Namespace) -> int:
+    result = scaffold.compose_mcp(_repo_root(args), args.names, force=args.force)
+    _emit(result)
+    return 1 if result["unknown"] else 0
+
+
+def cmd_add_skill(args: argparse.Namespace) -> int:
+    result = scaffold.add_skill(_repo_root(args), args.name, force=args.force)
+    _emit(result)
+    return 0 if result.get("ok") else 1
+
+
+def cmd_list_skills(args: argparse.Namespace) -> int:
+    _emit({"library_skills": scaffold.list_library_skills()})
+    return 0
+
+
+def cmd_sync(args: argparse.Namespace) -> int:
+    _emit(scaffold.sync(_repo_root(args)))
+    return 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    result = scaffold.doctor(_repo_root(args))
+    _emit(result)
+    return 0 if result["ok"] else 1
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    _emit(scaffold.status(_repo_root(args)))
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    _emit({"specced": scaffold.SPECCED_VERSION, "engine": scaffold.engine_version()})
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="specced",
+        description="Install and manage the specced agentic coding setup in a repo.",
+    )
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--repo-root",
+        default=None,
+        help="Path inside the target repo. Defaults to the current directory.",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser(
+        "init", parents=[common], help="Install the setup into the repo (idempotent)."
+    )
+    p_init.add_argument(
+        "--preset",
+        default=None,
+        help="Stack preset name, or 'auto' to detect (see: specced presets).",
+    )
+    p_init.add_argument(
+        "--minimal",
+        action="store_true",
+        help="Install only the engine, agents, managed blocks, and config "
+        "(skip Layer-2 content files so the interview can author them).",
+    )
+    p_init.add_argument("--force", action="store_true", help="Overwrite existing files.")
+    p_init.add_argument(
+        "--format-cmd",
+        default=None,
+        help="Format+lint command for the Stop hook (default: 'make fmt lint').",
+    )
+    p_init.set_defaults(func=cmd_init)
+
+    p_detect = sub.add_parser(
+        "detect", parents=[common], help="Inspect the repo and report stack signals (JSON)."
+    )
+    p_detect.set_defaults(func=cmd_detect)
+
+    p_presets = sub.add_parser("presets", help="List available stack presets.")
+    p_presets.set_defaults(func=cmd_presets)
+
+    p_mcp = sub.add_parser(
+        "add-mcp", parents=[common], help="Add MCP servers to .mcp.json from the catalog."
+    )
+    p_mcp.add_argument(
+        "names", nargs="+", help="Server names (see 'mcp_catalog' in: specced status)."
+    )
+    p_mcp.add_argument("--force", action="store_true", help="Overwrite an existing server entry.")
+    p_mcp.set_defaults(func=cmd_add_mcp)
+
+    p_add = sub.add_parser(
+        "add-skill", parents=[common], help="Install a domain skill from the library."
+    )
+    p_add.add_argument("name", help="Library skill name (see: specced list-skills).")
+    p_add.add_argument("--force", action="store_true", help="Replace if already present.")
+    p_add.set_defaults(func=cmd_add_skill)
+
+    p_list = sub.add_parser("list-skills", help="List available library skills.")
+    p_list.set_defaults(func=cmd_list_skills)
+
+    p_sync = sub.add_parser(
+        "sync",
+        parents=[common],
+        help="Refresh engine + agents + managed blocks to this specced version.",
+    )
+    p_sync.set_defaults(func=cmd_sync)
+
+    p_doctor = sub.add_parser("doctor", parents=[common], help="Verify the setup is consistent.")
+    p_doctor.set_defaults(func=cmd_doctor)
+
+    p_status = sub.add_parser(
+        "status", parents=[common], help="Show installed components and config."
+    )
+    p_status.set_defaults(func=cmd_status)
+
+    p_version = sub.add_parser("version", help="Print specced and engine versions.")
+    p_version.set_defaults(func=cmd_version)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())