project-init 0.3.0__py3-none-any.whl

project_init/templates/base/dot_claude/docs/guides/issue-metadata.md

@@ -0,0 +1,27 @@
+# Issue metadata
+
+Issues carry planning metadata in two places.
+
+## GitHub labels
+
+Use labels for values that workflows and project boards can read.
+
+- Type labels: `feature`, `bug`, `chore`, `documentation`, `test`
+- Priority labels: `priority:high`, `priority:medium`, `priority:low`
+- Size labels: `size:XS`, `size:S`, `size:M`, `size:L`, `size:XL`
+- Area labels are repository-specific. Use existing labels only; do not invent new area labels from agent context.
+
+`create_issue.sh` creates missing priority and size labels when the token has permission. If label creation fails, the issue is still created and the value remains in the markdown body.
+
+## Markdown body
+
+Use the markdown body for context GitHub does not model portably:
+
+- references to issues, PRs, ADRs, docs, designs, logs, or external links
+- dependencies, blocked-by, parent, and follow-up relationships
+- acceptance criteria
+- implementation notes and affected areas
+- Definition of Ready
+- Definition of Done
+
+GitHub Projects fields are synced opportunistically by `board-automation.yml`. Missing fields or options are logged and skipped so issue creation does not fail in a new repository.

project_init/templates/base/dot_claude/docs/guides/secrets.md

@@ -0,0 +1,50 @@
+# Secrets handling
+
+How secrets flow through this project, and when to escalate beyond `.env`.
+
+## The local pattern (scaffolded)
+
+- `.env.example` documents every variable the project needs — committed,
+  values empty.
+- `.env` holds your real local values — gitignored, never committed.
+- Loading order: shell exports win over `.env`; tools load `.env`
+  explicitly (`uv run --env-file .env`, bun auto-load, or direnv).
+- Enforcement: the pre-commit hook runs a gitleaks scan and CI re-scans
+  the full history (ADR-007). A leaked value that reaches a commit must be
+  **rotated**, not just deleted — assume it is compromised.
+
+## When .env stops being enough
+
+`.env` files do not scale past a single developer: no audit trail, no
+rotation, manual sharing. Escalate to a secret manager when the team or
+the secret count grows. Common paths, in rough order of adoption effort:
+
+| Option | Shape | Fits when |
+|---|---|---|
+| [sops](https://github.com/getsops/sops) + age | encrypted files in the repo | small teams, GitOps workflows, no SaaS dependency |
+| [1Password CLI](https://developer.1password.com/docs/cli/) (`op run`) | secrets injected from a shared vault | team already uses 1Password |
+| [Doppler](https://docs.doppler.com/) | hosted secret manager with env sync | many environments/services, need audit + rotation |
+| Cloud-native (AWS/GCP/Azure secret managers) | IAM-scoped, per-service | production workloads already on that cloud |
+
+The scaffolder deliberately installs **none** of these — the choice is
+org-specific. Whichever you pick, keep the contract: `.env.example` stays
+the documentation of record for *what* variables exist; the manager owns
+*values*.
+
+## Credential separation (the actual prod-safety boundary)
+
+The `prod_guard` hook flags destructive commands (`terraform destroy`,
+`DROP DATABASE`, cloud deletes — see the `prod_guard` hook), but a
+deny-list is a guardrail, not a guarantee (ADR-012). The guarantee is that
+**agent sessions never hold production credentials**:
+
+- `.env` files used in agent sessions contain dev/staging values only.
+- Production credentials live in the secret manager and are injected
+  exclusively into review-gated CI deploy jobs — never into a local shell
+  an agent runs in.
+- A guard cannot delete what the session cannot reach.
+
+## CI secrets
+
+Use the platform's mechanism (GitHub Actions secrets/environments), never
+files in the repo. Scope them per-environment and rotate on offboarding.

project_init/templates/base/dot_claude/docs/guides/using-memory.md

@@ -0,0 +1,36 @@
+# Using Memory
+
+Two complementary memory systems work together in this project.
+
+## `.claude/memory/` — Agent recall
+
+Small, structured facts that agents read at the start of each session.
+
+- **Index:** `memory/MEMORY.md` — one line per memory file, loaded every session
+- **Files:** `memory/<topic>.md` with frontmatter (`name`, `description`, `type`)
+- **Types:** `user`, `feedback`, `project`, `reference`
+- **When to write:** Learning something reusable that would save time next session
+
+Quick-save via slash command:
+```
+/save_memory <fact>
+```
+
+## `.claude/vault/` — Human workspace
+
+Exploratory notes, session logs, design sketches. Managed in Obsidian.
+
+- **Sessions:** `vault/sessions/YYYY-MM-DD.md` — written by the `/session_summary` skill
+- **Decisions:** `vault/decisions/` — working notes before a decision solidifies
+- **Knowledge:** `vault/knowledge/` — concepts, research, architecture explorations
+
+## The one-way flow
+
+When an exploratory vault note becomes a real decision:
+
+1. Create `docs/adr/adr-NNN-<topic>.md` (see existing ADRs for format)
+2. Update `docs/README.md` to link the new ADR
+3. Commit and push
+4. Delete or summarise the vault note (avoid duplication)
+
+Agents read `docs/adr/` — not vault — for authoritative decisions.

project_init/templates/base/dot_claude/hooks/README.md

@@ -0,0 +1,15 @@
+# `.claude/hooks/`
+
+Session hooks — deterministic bash or python scripts. The `settings.json` at `.claude/settings.json` wires them to Claude Code events (SessionStart, SessionEnd, PreToolUse, etc.).
+
+Keep hooks fast, idempotent, and non-interactive.
+
+These hooks are fast-feedback UX for Claude Code sessions — they are not the
+security boundary. Secret scanning (gitleaks) and lifecycle gating run as git
+hooks installed by `.claude/scripts/install_hooks.sh`, with CI as the
+backstop, so they bind every agent and every human (ADR-007).
+
+## Hook Executability Convention
+
+- **Shell hooks** (`.sh` files): Must have the executable bit (`+x`). They run directly via `bash path/to/hook.sh`.
+- **Python hooks** (`.py` files): Do NOT need the executable bit. They are invoked via `python3 path/to/hook.py`.

project_init/templates/base/dot_claude/hooks/agent_guard_adapter.py.tmpl

@@ -0,0 +1,64 @@
+{{#if multi_agent}}#!/usr/bin/env python3
+"""Adapt non-Claude agent hook payloads for the shared dag_workflow guard.
+
+Codex (PreToolUse via .codex/hooks.json) and Gemini CLI (BeforeTool via the
+project extension) reuse the same COMMAND_RULES enforcement Claude Code gets
+from github_command_guard.sh. Payloads differ slightly per agent, so this
+shim extracts the shell command, feeds a Claude-shaped payload into
+dag_workflow.py guard, and translates the verdict to the caller's dialect:
+
+  codex  -> {"decision": "block", ...} (Codex accepts Claude's shape)
+  gemini -> {"decision": "deny",  ...}
+
+Fail-open by design: on any parse error the command proceeds — git hooks
+and CI remain the real enforcement boundary (ADR-007).
+
+Usage (wired by the scaffolded hook configs): agent_guard_adapter.py <dialect>
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _extract_command(payload: dict) -> str:
+    tool_input = payload.get("tool_input") or payload.get("toolInput") or {}
+    command = tool_input.get("command") or tool_input.get("cmd") or ""
+    if isinstance(command, list):
+        command = " ".join(str(part) for part in command)
+    return str(command)
+
+
+def main() -> int:
+    dialect = sys.argv[1] if len(sys.argv) > 1 else "codex"
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except json.JSONDecodeError:
+        return 0
+    command = _extract_command(payload)
+    if not command:
+        return 0
+
+    guard = Path(__file__).with_name("dag_workflow.py")
+    proc = subprocess.run(
+        [sys.executable, str(guard), "guard"],
+        input=json.dumps({"tool_input": {"command": command}}),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    try:
+        verdict = json.loads(proc.stdout.strip() or "null")
+    except json.JSONDecodeError:
+        return 0
+    if isinstance(verdict, dict) and verdict.get("decision") == "block":
+        if dialect == "gemini":
+            verdict = {"decision": "deny", "reason": verdict.get("reason", "")}
+        sys.stdout.write(json.dumps(verdict))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+{{/if multi_agent}}