beacon-framework 0.1.0__py3-none-any.whl

beacon/__init__.py

@@ -0,0 +1,3 @@
+"""BEACON Framework: lifecycle and discipline for artifact-driven AI-assisted delivery."""
+
+__version__ = "0.1.0"

beacon/__main__.py

@@ -0,0 +1,4 @@
+from beacon.cli import app
+
+if __name__ == "__main__":
+    app()

beacon/cli.py

@@ -0,0 +1,177 @@
+"""BEACON CLI — install, upgrade, validate, and manage AI integrations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from beacon import __version__, installer, integrations
+from beacon.manifest import MANIFEST_RELPATH, Manifest
+from beacon.upgrader import upgrade as upgrade_project
+
+app = typer.Typer(
+    name="beacon",
+    help="BEACON Framework — lifecycle and discipline for artifact-driven AI-assisted delivery.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+integration_app = typer.Typer(
+    name="integration",
+    help="Manage AI tool integrations (Claude Code, ...).",
+    no_args_is_help=True,
+)
+app.add_typer(integration_app)
+
+console = Console()
+
+
+def _resolve_root(here: bool, path: Path | None) -> Path:
+    if here and path is not None:
+        raise typer.BadParameter("Pass either --here or PATH, not both.")
+    if here:
+        return Path.cwd()
+    if path is not None:
+        return path.resolve()
+    return Path.cwd()
+
+
+@app.command()
+def version() -> None:
+    """Print the installed BEACON version."""
+    console.print(f"beacon {__version__}")
+
+
+@app.command()
+def init(
+    path: Path | None = typer.Argument(None, help="Project directory (default: cwd)."),
+    here: bool = typer.Option(False, "--here", help="Install into the current directory."),
+    ai: list[str] = typer.Option(
+        ["claude"],
+        "--ai",
+        help="AI integration(s) to wire up.",
+    ),
+) -> None:
+    """Install BEACON into a project. Idempotent: existing user files are preserved."""
+    root = _resolve_root(here, path)
+    root.mkdir(parents=True, exist_ok=True)
+
+    existing = Manifest.load(root)
+    manifest = existing or Manifest.fresh()
+
+    framework_written, user_seeded_written = installer.install_core(root, overwrite_framework=True)
+
+    for name in ai:
+        try:
+            integrations.install(name, root)
+        except KeyError as e:
+            raise typer.BadParameter(str(e)) from e
+
+    manifest.beacon_version = __version__
+    manifest.ai = sorted(set(manifest.ai) | set(ai))
+    manifest.framework_files = sorted(set(manifest.framework_files) | set(framework_written))
+    manifest.user_seeded_files = sorted(set(manifest.user_seeded_files) | set(user_seeded_written))
+    manifest.save(root)
+
+    console.print(f"[green]✓[/green] BEACON {__version__} installed at [cyan]{root}[/cyan]")
+    console.print(f"  framework files written: {len(framework_written)}")
+    console.print(f"  user-seeded files written: {len(user_seeded_written)} (existing left intact)")
+    console.print(f"  integrations: {', '.join(manifest.ai) or 'none'}")
+    console.print(f"  manifest: [dim]{MANIFEST_RELPATH}[/dim]")
+
+
+@app.command()
+def upgrade(
+    path: Path | None = typer.Argument(None, help="Project directory (default: cwd)."),
+    here: bool = typer.Option(False, "--here", help="Upgrade in the current directory."),
+) -> None:
+    """Refresh BEACON framework files. User-seeded content is left untouched."""
+    root = _resolve_root(here, path)
+    try:
+        manifest, touched = upgrade_project(root)
+    except FileNotFoundError as e:
+        raise typer.Exit(code=1) from typer.BadParameter(str(e))
+    console.print(f"[green]✓[/green] BEACON upgraded to {manifest.beacon_version}")
+    console.print(f"  files refreshed: {len(touched)}")
+    console.print(f"  integrations: {', '.join(manifest.ai) or 'none'}")
+
+
+@app.command()
+def check(
+    path: Path | None = typer.Argument(None, help="Project directory (default: cwd)."),
+    here: bool = typer.Option(False, "--here", help="Check the current directory."),
+) -> None:
+    """Validate a BEACON install: manifest present and required files in place."""
+    root = _resolve_root(here, path)
+    manifest = Manifest.load(root)
+    if manifest is None:
+        console.print(
+            f"[red]✗[/red] No BEACON manifest at {root / MANIFEST_RELPATH}. "
+            f"Run `beacon init` first."
+        )
+        raise typer.Exit(code=1)
+
+    missing: list[str] = []
+    for rel in manifest.framework_files:
+        if not (root / rel).exists():
+            missing.append(rel)
+
+    if missing:
+        console.print(f"[red]✗[/red] {len(missing)} framework files missing:")
+        for rel in missing:
+            console.print(f"    - {rel}")
+        console.print("  Run `beacon upgrade` to restore.")
+        raise typer.Exit(code=1)
+
+    console.print(
+        f"[green]✓[/green] BEACON {manifest.beacon_version} OK at [cyan]{root}[/cyan] "
+        f"(integrations: {', '.join(manifest.ai) or 'none'})"
+    )
+
+
+@integration_app.command("list")
+def integration_list() -> None:
+    """List available AI integrations."""
+    for name in integrations.names():
+        console.print(f"  - {name}")
+
+
+@integration_app.command("add")
+def integration_add(
+    name: str,
+    path: Path | None = typer.Argument(None, help="Project directory (default: cwd)."),
+    here: bool = typer.Option(False, "--here"),
+) -> None:
+    """Add an AI integration to an existing BEACON install."""
+    root = _resolve_root(here, path)
+    manifest = Manifest.load(root)
+    if manifest is None:
+        raise typer.BadParameter("No BEACON manifest. Run `beacon init` first.")
+    try:
+        integrations.install(name, root)
+    except KeyError as e:
+        raise typer.BadParameter(str(e)) from e
+    manifest.ai = sorted(set(manifest.ai) | {name})
+    manifest.save(root)
+    console.print(f"[green]✓[/green] integration added: {name}")
+
+
+@integration_app.command("remove")
+def integration_remove(
+    name: str,
+    path: Path | None = typer.Argument(None, help="Project directory (default: cwd)."),
+    here: bool = typer.Option(False, "--here"),
+) -> None:
+    """Remove an AI integration; manifest is updated accordingly."""
+    root = _resolve_root(here, path)
+    manifest = Manifest.load(root)
+    if manifest is None:
+        raise typer.BadParameter("No BEACON manifest. Run `beacon init` first.")
+    try:
+        integrations.remove(name, root)
+    except KeyError as e:
+        raise typer.BadParameter(str(e)) from e
+    manifest.ai = sorted(set(manifest.ai) - {name})
+    manifest.save(root)
+    console.print(f"[green]✓[/green] integration removed: {name}")

beacon/installer.py

@@ -0,0 +1,92 @@
+"""File installation logic for BEACON.
+
+Two file categories with different upgrade semantics:
+
+- **framework**: shipped by the package, always overwritten on ``beacon init``
+  and ``beacon upgrade``. Users should not edit these.
+- **user_seeded**: shipped as a starting point. Written by ``init`` only if
+  absent; ``upgrade`` never touches them.
+
+The classification is data, not code: see ``FRAMEWORK_RELPATHS`` and
+``USER_SEEDED_RELPATHS`` below.
+"""
+
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+
+# Paths are relative to the *target project root*, and mirror the layout under
+# ``src/beacon/resources/``.
+USER_SEEDED_RELPATHS: tuple[str, ...] = (
+    "beacon.md",
+    "project-management/Background/00-problem-statement.md",
+    "project-management/Background/01-final-architecture-document.md",
+    "project-management/Roadmap/README.md",
+)
+
+FRAMEWORK_RELPATHS: tuple[str, ...] = (
+    "project-management/ADRs/README.md",
+    "project-management/ADRs/ADR-000-template.md",
+    "project-management/Prompts/01-SEED.md",
+    "project-management/Prompts/02-DESIGN.md",
+    "project-management/Prompts/03-BUILD.md",
+    "project-management/Prompts/04-SHIP.md",
+    "project-management/Work/README.md",
+)
+
+GITKEEP_RELPATHS: tuple[str, ...] = (
+    "project-management/Roadmap/archive/.gitkeep",
+    "project-management/Work/analysis/.gitkeep",
+    "project-management/Work/planning/.gitkeep",
+    "project-management/Work/sessions/.gitkeep",
+)
+
+
+def _resource_root() -> Path:
+    """Return the on-disk path to the packaged ``resources/`` directory."""
+    return Path(str(resources.files("beacon").joinpath("resources")))
+
+
+def _copy_one(src: Path, dst: Path) -> None:
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(src, dst)
+
+
+def install_core(project_root: Path, *, overwrite_framework: bool) -> tuple[list[str], list[str]]:
+    """Install the BEACON core file set into ``project_root``.
+
+    ``overwrite_framework=False`` is the ``init`` behaviour (seed only what's
+    missing). ``True`` is the ``upgrade`` behaviour: refresh framework files,
+    leave user_seeded alone.
+    """
+    src_root = _resource_root()
+    framework_written: list[str] = []
+    user_seeded_written: list[str] = []
+
+    for rel in FRAMEWORK_RELPATHS:
+        src = src_root / rel
+        dst = project_root / rel
+        if dst.exists() and not overwrite_framework:
+            continue
+        _copy_one(src, dst)
+        framework_written.append(rel)
+
+    for rel in USER_SEEDED_RELPATHS:
+        src = src_root / rel
+        dst = project_root / rel
+        if dst.exists():
+            continue  # never overwrite user-seeded files
+        _copy_one(src, dst)
+        user_seeded_written.append(rel)
+
+    for rel in GITKEEP_RELPATHS:
+        dst = project_root / rel
+        if dst.exists():
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        dst.touch()
+        framework_written.append(rel)
+
+    return framework_written, user_seeded_written

beacon/integrations/__init__.py

@@ -0,0 +1,36 @@
+"""AI tool integrations for BEACON.
+
+The registry below is the single source of truth for which integrations exist.
+Adding a new one (Copilot, Gemini, ...) is one entry plus one module.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from beacon.integrations import claude_code
+
+# Each entry exposes (install, remove) callables. Both take ``project_root`` and
+# return the list of relative paths written or removed.
+Integration = tuple[Callable[[Path], list[str]], Callable[[Path], list[str]]]
+
+REGISTRY: dict[str, Integration] = {
+    "claude": (claude_code.install, claude_code.remove),
+}
+
+
+def names() -> list[str]:
+    return sorted(REGISTRY.keys())
+
+
+def install(name: str, project_root: Path) -> list[str]:
+    if name not in REGISTRY:
+        raise KeyError(f"Unknown integration: {name}. Available: {names()}")
+    return REGISTRY[name][0](project_root)
+
+
+def remove(name: str, project_root: Path) -> list[str]:
+    if name not in REGISTRY:
+        raise KeyError(f"Unknown integration: {name}. Available: {names()}")
+    return REGISTRY[name][1](project_root)

beacon/integrations/claude_code.py

@@ -0,0 +1,123 @@
+"""Claude Code integration.
+
+Installs slash commands under ``.claude/commands/`` and a marker-delimited
+fragment into ``.claude/CLAUDE.md``. The fragment is the only place where
+BEACON's lifecycle and Spec Kit seams are described — by design.
+"""
+
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+
+INTEGRATION_NAME = "claude"
+RESOURCE_SUBDIR = "integrations/claude_code"
+
+# Slash command files installed under ``.claude/commands/``. Always overwritten
+# by ``install`` / ``upgrade`` — BEACON owns these.
+COMMAND_RELPATHS: tuple[str, ...] = (
+    ".claude/commands/init.md",
+    ".claude/commands/git/feature.md",
+    ".claude/commands/git/pr.md",
+    ".claude/commands/git/release.md",
+    ".claude/commands/design/diagram.md",
+    ".claude/commands/design/evaluate.md",
+    ".claude/commands/design/wardley.md",
+)
+
+CLAUDE_MD = Path(".claude/CLAUDE.md")
+START_MARKER = "<!-- BEACON START -->"
+END_MARKER = "<!-- BEACON END -->"
+
+
+def _resource_root() -> Path:
+    return Path(str(resources.files("beacon").joinpath("resources").joinpath(RESOURCE_SUBDIR)))
+
+
+def _copy_command(rel: str, project_root: Path) -> None:
+    src = _resource_root() / "commands" / rel.removeprefix(".claude/commands/")
+    dst = project_root / rel
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(src, dst)
+
+
+def _read_fragment() -> str:
+    return (_resource_root() / "CLAUDE.md.fragment").read_text()
+
+
+def _inject_fragment(project_root: Path) -> None:
+    """Write or refresh the BEACON-managed block in ``.claude/CLAUDE.md``.
+
+    If the file does not exist, create it with just the fragment.
+    If markers are present, replace what's between them.
+    If markers are absent, append the fragment.
+    """
+    path = project_root / CLAUDE_MD
+    fragment = _read_fragment().rstrip() + "\n"
+
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(fragment)
+        return
+
+    content = path.read_text()
+    start = content.find(START_MARKER)
+    end = content.find(END_MARKER)
+    if start != -1 and end != -1 and end > start:
+        end_line = content.find("\n", end)
+        end_idx = end_line + 1 if end_line != -1 else len(content)
+        new = content[:start] + fragment + content[end_idx:]
+        path.write_text(new)
+        return
+
+    sep = "" if content.endswith("\n") else "\n"
+    path.write_text(content + sep + "\n" + fragment)
+
+
+def _strip_fragment(project_root: Path) -> None:
+    path = project_root / CLAUDE_MD
+    if not path.exists():
+        return
+    content = path.read_text()
+    start = content.find(START_MARKER)
+    end = content.find(END_MARKER)
+    if start == -1 or end == -1 or end <= start:
+        return
+    end_line = content.find("\n", end)
+    end_idx = end_line + 1 if end_line != -1 else len(content)
+    cleaned = content[:start] + content[end_idx:]
+    # Collapse consecutive blank lines at the seam
+    while "\n\n\n" in cleaned:
+        cleaned = cleaned.replace("\n\n\n", "\n\n")
+    path.write_text(cleaned)
+
+
+def install(project_root: Path) -> list[str]:
+    """Install Claude Code integration. Returns relpaths written."""
+    written: list[str] = []
+    for rel in COMMAND_RELPATHS:
+        _copy_command(rel, project_root)
+        written.append(rel)
+    _inject_fragment(project_root)
+    written.append(str(CLAUDE_MD))
+    return written
+
+
+def remove(project_root: Path) -> list[str]:
+    """Remove Claude Code integration. Returns relpaths removed/modified."""
+    removed: list[str] = []
+    for rel in COMMAND_RELPATHS:
+        p = project_root / rel
+        if p.exists():
+            p.unlink()
+            removed.append(rel)
+            # Clean empty parent dirs (best effort)
+            for parent in (p.parent, p.parent.parent):
+                try:
+                    parent.rmdir()
+                except OSError:
+                    break
+    _strip_fragment(project_root)
+    removed.append(str(CLAUDE_MD))
+    return removed

beacon/manifest.py

@@ -0,0 +1,55 @@
+"""BEACON installation manifest — the atomicity contract.
+
+A manifest lives at ``project-management/.beacon/init-options.json`` and records:
+- the package version used to install,
+- which AI integrations are wired up,
+- which files BEACON owns (``framework`` — overwritten by upgrade) versus
+  which it merely seeded (``user_seeded`` — never overwritten).
+
+The manifest is what makes ``beacon upgrade`` safe: it knows exactly which
+files it may touch and which belong to the user.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from beacon import __version__
+
+MANIFEST_RELPATH = Path("project-management/.beacon/init-options.json")
+
+
+@dataclass
+class Manifest:
+    beacon_version: str = __version__
+    installed_at: str = ""
+    ai: list[str] = field(default_factory=list)
+    framework_files: list[str] = field(default_factory=list)
+    user_seeded_files: list[str] = field(default_factory=list)
+
+    @classmethod
+    def fresh(cls) -> Manifest:
+        return cls(installed_at=datetime.now(timezone.utc).isoformat(timespec="seconds"))
+
+    @classmethod
+    def load(cls, project_root: Path) -> Manifest | None:
+        path = project_root / MANIFEST_RELPATH
+        if not path.exists():
+            return None
+        data = json.loads(path.read_text())
+        return cls(
+            beacon_version=data.get("beacon_version", ""),
+            installed_at=data.get("installed_at", ""),
+            ai=list(data.get("ai", [])),
+            framework_files=list(data.get("framework_files", [])),
+            user_seeded_files=list(data.get("user_seeded_files", [])),
+        )
+
+    def save(self, project_root: Path) -> Path:
+        path = project_root / MANIFEST_RELPATH
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(asdict(self), indent=2, sort_keys=True) + "\n")
+        return path

beacon/resources/beacon.md

@@ -0,0 +1,9 @@
+# Progress
+
+> "Would I proudly sign my name to this?"
+
+| Phase | Active Bullet | Branch | Last DEV deploy |
+|---|---|---|---|
+| SEED → **DESIGN** → BUILD → SHIP | `#— —` | `—` | `—` |
+
+See [`project-management/Roadmap/README.md`](project-management/Roadmap/README.md) for the full plan.

beacon/resources/integrations/claude_code/CLAUDE.md.fragment

@@ -0,0 +1,137 @@
+<!-- BEACON START -->
+<!-- Managed by `uvx beacon`. Edit content outside these markers. -->
+
+## BEACON Framework
+
+You are a BEACON Framework assistant. Prime directive at all times:
+
+> **"Would I proudly sign my name to this?"**
+
+BEACON is a pragmatic, artifact-driven framework that combines tracer-bullet delivery with disciplined craftsmanship. Pair it with [Spec Kit](https://github.com/github/spec-kit) for the spec mechanics inside DESIGN and BUILD.
+
+### Phases
+
+```
+SEED → DESIGN → BUILD → SHIP
+```
+
+| Phase | Entry | Deliverables | Exit |
+|---|---|---|---|
+| **SEED** | "I have an idea for…" / new project | `project-management/Background/00-problem-statement.md` | One problem, one user, success criteria, non-goals |
+| **DESIGN** | "How should we architect…" / "Break this down" | `specs/[feature]/{spec,plan,tasks}.md` (Spec Kit); `project-management/ADRs/ADR-NNN-*.md`; updated `Background/01-final-architecture-document.md` | spec, plan, tasks complete and reviewed |
+| **BUILD** | "Starting bullet #N" | Working software per bullet; updated `beacon.md` + Roadmap | All tests pass; previous bullets unbroken; demoable |
+| **SHIP** | All bullets complete | PR via `/git:pr`; `Work/` cleaned; patterns promoted to ADRs | PR merged to `main`; clean `Work/` |
+
+Full prompts: `project-management/Prompts/0N-PHASE.md`.
+
+### Pipeline (Claude Code)
+
+```
+/init                                 # SEED — produces 00-problem-statement.md
+  └── /speckit.specify "<feature>"    # DESIGN — produces specs/NNN-slug/spec.md
+        └── /speckit.plan             # DESIGN — produces plan.md
+              └── /speckit.tasks      # DESIGN — produces tasks.md
+                    └── /speckit.implement   # BUILD — executes tasks
+                          └── /git:pr        # SHIP — PR to develop
+                                └── /git:release   # SHIP — develop → main
+```
+
+### Tracer bullets
+
+A tracer bullet is a complete minimal path through the system, end-to-end:
+- Touches all layers (even minimally)
+- Produces user-visible output
+- Deployable as-is (even if limited)
+- 2–4 hours max — split if larger
+- Vertical, not horizontal: day 1 ships hardcoded end-to-end; day 2 adds real logic
+
+One bullet per session. Scope creep goes to `project-management/Work/planning/future-features.md`.
+
+### Git workflow (two-branch environment model)
+
+```
+main     ── PROD  (protected; PR from develop only; manual approval)
+  ↑ /git:release
+develop  ── DEV   (protected; CI gates only)
+  ↑ /git:pr
+NNN-slug                                                 ← spec work (from /speckit.specify)
+feature/[slug] · fix/[slug] · chore/[slug] · docs/[slug] ← non-spec (/git:feature)
+```
+
+| Command | Action |
+|---|---|
+| `/speckit.specify <feature>` | Create spec + `NNN-slug` branch |
+| `/git:feature <name>` | Cut branch from `develop` for non-spec work |
+| `/git:pr` | PR to `develop` |
+| `/git:release` | PR `develop → main` with changelog |
+
+Conventional Commits enforced by the `commit-msg` hook. Do not bypass.
+
+### Project management
+
+```
+project-management/
+├── Background/   ← problem statement, architecture (PERMANENT)
+├── ADRs/         ← MADR-format decisions (PERMANENT, immutable)
+├── Roadmap/      ← cross-feature bullet dashboard (PERMANENT)
+├── Prompts/      ← phase prompts (PERMANENT, framework-owned)
+└── Work/         ← scratchpad (TRANSIENT — delete after merge)
+    ├── sessions/ planning/ analysis/
+```
+
+Anything important that lives only in `Work/` will be lost. Promote insights to ADRs before deleting.
+
+### Seams with Spec Kit
+
+These are the only places BEACON and Spec Kit touch — everywhere else they are independent:
+
+1. `/init` → `/speckit.specify` — BEACON's SEED phase ends by bridging to Spec Kit's DESIGN.
+2. **Roadmap aggregates; tasks.md decomposes.** `Roadmap/README.md` is the cross-feature dashboard; `specs/[feature]/tasks.md` is the within-feature breakdown. Roadmap rows link to spec paths.
+3. **Feature-scoped research → `specs/[feature]/research.md`. Cross-cutting analysis → `Work/analysis/`.**
+4. **Constitution Check ≠ ADR.** `.specify/memory/constitution.md` = project principles enforced by Spec Kit's plan gate. `project-management/ADRs/` = specific decisions with rationale. They coexist.
+
+### Where principles live
+
+| Document | Scope | Owner | Updated by |
+|---|---|---|---|
+| `pragmatic-principles.md` | Universal craftsperson agent OS | `beacon` package | `uvx beacon upgrade` |
+| `.specify/memory/constitution.md` | This project's rules | `specify` | `/speckit.constitution` |
+| `project-management/ADRs/` | Specific decisions, immutable | `beacon` package (template) + humans/agent | Manual / `/speckit.plan` discovery |
+
+### Pragmatic design principles (applied as constraints)
+
+| Principle | Test |
+|---|---|
+| **DRY** | Is this logic defined in exactly one place? |
+| **Orthogonality** | Can this change without forcing changes elsewhere? |
+| **Reversibility** | What is the escape hatch if we change this decision? |
+| **Simplicity** | Is this the simplest thing that could work? Function before class. Script before service. |
+| **Broken Windows** | Any TODOs, warnings, or failing tests I'm walking past? |
+
+### Quality gates (before any bullet is "done")
+
+```bash
+uv run ruff check --fix
+uv run ruff format
+uv run ty check
+```
+
+Then ask: *"Would I sign my name to this?"* If not, refactor before committing.
+
+### WISDOM communication (ADRs, PRs, tradeoffs)
+
+- **W**hat do you want the reader to understand?
+- **I**nterest level and stake?
+- **S**ophistication with this domain?
+- **D**etail they need?
+- **O**wnership you want to create?
+- **M**otivation to engage?
+
+### Upgrading
+
+- Upgrade BEACON: `uvx beacon upgrade` — refreshes `project-management/Prompts/` and templates; preserves your `Background/`, `ADRs/`, `Roadmap/`, `Work/`.
+- Upgrade Spec Kit: `uvx specify integration upgrade` — refreshes `.specify/` and `.github/{agents,prompts}/`; does not touch BEACON files.
+
+Neither upgrade can modify the other framework's directory.
+
+<!-- BEACON END -->