project-init 0.3.0__py3-none-any.whl

project_init/templates/base/dot_claude/memory/SCHEMA.md

@@ -0,0 +1,52 @@
+# Memory Schema
+
+Authoritative governance for `.claude/memory/` files. `lint_memory.sh` enforces these rules.
+
+## Required frontmatter
+
+Every memory file (except MEMORY.md, SCHEMA.md, README.md) must have:
+
+```yaml
+---
+name: <short title>
+description: <one-line summary used for relevance ranking>
+type: user | feedback | project | reference
+---
+```
+
+## Types
+
+| Type | Purpose | Body structure |
+|---|---|---|
+| `user` | About the human — role, preferences, expertise | Free-form |
+| `feedback` | Rules/corrections the user has given | **Why:** + **How to apply:** |
+| `project` | Current-state facts — goals, deadlines, decisions | **Why:** + **How to apply:** |
+| `reference` | Pointers to external systems — URLs, dashboards | Free-form |
+
+## File naming
+
+Convention (not enforced by lint): `<type>_<slug>.md` — lowercase, hyphenated slug.
+
+Examples: `user_role.md`, `feedback_testing.md`, `project_deadline.md`, `reference_api-docs.md`
+
+## Index
+
+Every memory file must appear in `MEMORY.md` as a one-line bullet:
+
+```markdown
+- [Title](filename.md) — short description
+```
+
+Keep lines under ~150 characters. `lint_memory.sh` checks for orphaned files and stale index entries.
+
+## What NOT to store
+
+- Code patterns or architecture (derivable from the repo)
+- Git history (`git log`)
+- Ephemeral task state (use TODOs)
+- Anything already in `CLAUDE.md` or `project-init.md`
+- Large documents (put those in `vault/`)
+
+## Relationship to vault
+
+`memory/` holds small structured facts for fast agent recall. `vault/` holds richer human-authored documentation (Obsidian). When a vault note distills into a reusable fact, create a memory file and link back to the vault note for context.

project_init/templates/base/dot_claude/memory/feedback_conventions.md

@@ -0,0 +1,11 @@
+---
+name: Conventions feedback
+description: Rules about how agents should behave in this project
+type: feedback
+---
+
+<!-- Add corrections and confirmed approaches as they accumulate -->
+
+**Why:** <!-- why the convention matters -->
+
+**How to apply:** <!-- specific behavior change for agents -->

project_init/templates/base/dot_claude/memory/project_context.md.tmpl

@@ -0,0 +1,11 @@
+---
+name: Project context
+description: Goals, constraints, and key decisions for {{project_name}}
+type: project
+---
+
+<!-- Fill after scaffolding: why this project exists, key constraints, stakeholder goals -->
+
+**Why:** <!-- reason this project exists -->
+
+**How to apply:** <!-- how this context should shape agent suggestions -->

project_init/templates/base/dot_claude/memory/user_role.md

@@ -0,0 +1,7 @@
+---
+name: User role
+description: Who the developer is, their background, how to tailor responses
+type: user
+---
+
+<!-- Fill in: role, experience level, preferred languages/tools, communication style -->

project_init/templates/base/dot_claude/project-init.md.tmpl

@@ -0,0 +1,174 @@
+# Project: {{project_name}}
+
+> {{project_description}}
+
+Scaffolded with [project-init]({{project_init_url}}) on {{created_date}}.
+
+| | |
+|---|---|
+| Language | {{language}} |
+| Memory stack | {{memory_stack}} |
+| MCPs | {{installed_mcps}} |
+
+## Workflow
+
+1. **Start of session** — read [`memory/MEMORY.md`](memory/MEMORY.md), then check [`docs/adr/`](docs/adr/) for relevant decisions.
+2. **During work** — permanent decisions → [`docs/adr/`](docs/adr/); exploratory notes → [`vault/`](vault/); reusable facts → [`memory/`](memory/).
+3. **End of session** — run `/session_summary` to write a session log to [`vault/sessions/`](vault/sessions/).
+
+## Tools
+
+| Type | Name | Purpose |
+|---|---|---|
+| Command | `/status` | git state, recent commits, open TODOs |
+| Command | `/review` | code review of staged changes or a file |
+| Command | `/plan <task>` | acceptance tests first, then implementation plan |
+| Command | `/request_review` | mark PR ready for review, optional agent review |
+| Script | `create_issue.sh <type> "desc"` | create typed issue, prints issue number |
+| Script | `create_nojira_pr.sh <type> "desc"` | branch + push + draft PR without an issue |
+| Script | `setup_github.sh [branch] [--protect]` | provision board fields and review settings; `--protect` applies baseline branch protection |
+| Script | `start_issue.sh <n> <type>` | branch + draft PR |
+| Script | `promote_review.sh` | mark PR ready (board card moves automatically) |
+| Script | `monitor_pr.sh <n> [--merge]` | wait for CI; --merge squash-merges when clean |
+| Script | `finish_pr.sh [n] [--review-cycle N]` | push branch, mark ready, monitor checks/review, and merge |
+| Skill | `session_summary` | summarise session and save to vault |
+| Skill | `add_hook` | add a new deterministic hook |
+| Skill | `add_command` | add a new slash command |
+| Skill | `audit` | full project health scan, creates issue with findings |
+| Agent | `reviewer` | code review specialist |
+| Agent | `researcher` | codebase explorer |
+
+Hooks run automatically via `settings.json`: `github_command_guard`, `workflow_state_reminder`, `pre_commit_gate`, `post_edit_lint`. Secret scanning and lifecycle gating are enforced agent-agnostically by git hooks (gitleaks pre-commit, commit-msg, pre-push — installed via `.claude/scripts/install_hooks.sh`) and mirrored in CI; the `security-guidance` plugin provides Claude-side guidance.
+
+**Rules** (`.claude/rules/`): per-filetype conventions loaded automatically by Claude Code when you open a matching file.
+
+## Coding standards
+
+- No comments unless the WHY is non-obvious.
+- No premature abstractions — three similar lines before extracting.
+- No error handling for impossible scenarios.
+- No backwards-compatibility shims — delete removed code.
+- Prefer editing existing files over creating new ones.
+{{#if lint_command}}- `just lint` must pass before closing a task (`just --list` shows all recipes).
+{{/if}}
+
+## TDD
+
+Write failing tests before implementation. Tests define the contract.
+
+1. `/plan <task>` → acceptance tests (red)
+2. Commit failing tests
+3. Implement until green
+4. Lint and clean up
+{{#if python}}
+Test conventions: one assertion per test, name as `test_<unit>_<scenario>`, run with `uv run pytest`. Real DB/API instances — no mocks.
+{{/if}}
+
+## GitHub Projects tracking
+
+Work items are GitHub Issues; the project board is GitHub Projects (kanban with To Do / In Progress / In Review / Done columns). Board cards move automatically via `board-automation.yml` — **no manual board moves needed**.
+
+### Lifecycle: Issue → branch → draft PR → merge
+
+Every non-trivial task follows this exact sequence. Run the scripts; the LLM's only job is writing commit messages and fixing CI failures.
+
+| Step | Command | What happens automatically |
+|------|---------|---------------------------|
+| 1. Create issue | `.claude/scripts/create_issue.sh <type> "description" --priority <priority> --area "<area>" --size <size> --acceptance "<criterion>"` | Issue created with metadata, board card → **To Do** |
+| 2. Start work | `.claude/scripts/start_issue.sh <issue-n> <type>` | Branch (`<issue_type>/<project_abbr>-<issue_number>-<slug>`) + push + draft PR, board → **In Progress** |
+| 3. Commit | `git add … && git commit -m "type(<KEY>-<n>): message"` | `commit-msg` hook validates format; `pre_commit_gate` auto-lints |
+| 4. Push | `.claude/scripts/push_branch.sh` | CI runs; if it fails a comment is posted on the PR with `gh run view --log-failed` |
+| 5. Finish PR | `.claude/scripts/finish_pr.sh <n>` | Pushes, marks ready, monitors CI/review, and merges when clean |
+
+Steps 3–4 repeat until the work is complete. **When asked to push or finish a PR, keep going until the lifecycle is complete**: `finish_pr.sh` → fix any CI or review failures → rerun with the next review cycle until merged.
+
+### Merge setup (one-time per repo)
+
+Automated completion via `monitor_pr.sh --merge` works after checks pass. GitHub-native auto-merge requires two repo settings enabled by an admin:
+
+1. **GitHub Settings → General → Allow auto-merge** — tick the checkbox
+2. **Branch protection rule on `main`** — require CI status checks to pass
+
+Without GitHub-native auto-merge, `monitor_pr.sh --merge` still works by merging explicitly after CI passes.
+
+Run the scaffolded setup helper after creating the repository:
+
+```bash
+.claude/scripts/setup_github.sh --protect
+```
+
+It attempts to configure branch protection, required checks, conversation resolution, and Copilot code review. If GitHub does not expose a setting through the API or your token lacks permission, it prints the manual setup step.
+
+### Commit and PR format
+
+| What | Format | Example |
+|------|--------|---------|
+| Commit message | `<type>(KEY-<n>): description` | `feat(PI-42): Add OAuth login` |
+| PR title | `<type>(KEY-<n>): description` | `feat(PI-42): Add OAuth login` |
+| No-issue PR | `<type>: description` (no scope) | `fix: Fix typo` |
+| PR body | must include `Closes #<n>` | triggers auto-close on merge |
+| Branch | `<type>/<KEY>-<n>-<slug>` | `feat/PI-42-add-oauth-login` |
+
+Types: `feat` · `fix` · `chore` · `docs` · `test`
+
+For minor work without an issue, use `.claude/scripts/create_nojira_pr.sh <type> "description"`.
+It creates or reuses a typed `nojira` branch, pushes through `push_branch.sh`,
+and opens a draft PR titled `type: description` (no scope = no linked issue).
+
+### Rules
+
+- **No direct commits to `main`** — all changes through PRs. The `pre-push` hook enforces this locally.
+- Install hooks once after cloning:
+  ```bash
+  .claude/scripts/install_hooks.sh
+  ```
+- One issue → one branch → one PR.
+- Draft PRs created immediately when work starts — not when it's done.
+- PRs must pass CI (tests + lint) before merging.
+
+### Handling CI failures
+
+When CI fails, GitHub posts a comment on the PR. Read it, fix the code, push:
+```bash
+gh run view --log-failed   # full failure output
+# fix the code
+git add … && git commit -m "fix(<KEY>-<n>): Fix failing tests"
+.claude/scripts/push_branch.sh
+.claude/scripts/monitor_pr.sh <n> --merge   # wait and merge when clean
+```
+
+### Code review
+
+`finish_pr.sh` and `monitor_pr.sh --merge` wait for GitHub's review decision and print review feedback when changes are requested. Resolve actionable comments, post a review response, push with `.claude/scripts/push_branch.sh`, then rerun `monitor_pr.sh` with the next `--review-cycle`.
+
+`/request_review` may also invoke the local `reviewer` agent for an extra pre-merge pass; that agent review is optional, but the GitHub PR review gate is part of the normal lifecycle.
+
+### Quick reference
+
+```bash
+.claude/scripts/create_issue.sh <type> "description" --priority high --area docs --size S --acceptance "Done when ..."  # new issue → prints issue number
+.claude/scripts/start_issue.sh <n> <type>             # branch + draft PR
+.claude/scripts/create_nojira_pr.sh fix "description" # no-issue branch + draft PR
+.claude/scripts/setup_github.sh --protect            # one-time governance setup + branch protection
+.claude/scripts/promote_review.sh                     # mark PR ready for review
+.claude/scripts/monitor_pr.sh <n> --merge             # wait for CI, merge when clean
+.claude/scripts/finish_pr.sh <n>                      # push, ready, monitor, merge
+gh run view --log-failed                              # see what CI failed
+gh issue list                                         # open issues
+gh pr list                                            # open PRs
+```
+
+## Conventions
+
+- Hooks and scripts prefer bash/python. LLM calls only for generative steps.
+- `AGENTS.md` is the canonical root instruction file (the standard most agents read natively). `CLAUDE.md` and `GEMINI.md` redirect to it.
+- Everything else lives under `.claude/`.
+
+## Compact Instructions
+
+When compacting, preserve:
+- GitHub Issue number being worked on
+- Files modified this session
+- Test results (pass/fail count, failing test names)
+- Unresolved errors or lint failures
+- Decisions not yet committed to `docs/adr/`

project_init/templates/base/dot_claude/rules/go.md

@@ -0,0 +1,14 @@
+---
+description: Go environment and tooling
+globs: ["**/*.go", "go.mod", "go.sum"]
+alwaysApply: false
+---
+
+## Go environment
+
+```bash
+go build ./...
+go test ./... -count=1
+golangci-lint run
+gofmt -w .
+```

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

@@ -0,0 +1,30 @@
+---
+description: Hook reference — what each hook does and how to invoke manually
+globs: [".claude/settings.json", ".claude/hooks/**"]
+alwaysApply: false
+---
+
+## Hooks in this project
+
+All hooks fire automatically — do not invoke them manually in normal flow.
+
+| Hook | Event | Trigger |
+|---|---|---|
+| `github_command_guard.sh` | PreToolUse | Bash — steers agents toward lifecycle scripts |
+| `pre_commit_gate.sh` | PreToolUse | Bash containing `git commit` |
+| `post_edit_lint.sh` | PostToolUse | Edit / Write / MultiEdit |
+| `workflow_state_reminder.sh` | UserPromptSubmit | injects workflow lifecycle context |
+
+Security enforcement is agent-agnostic (ADR-007), not a Claude hook:
+secret scanning runs as a git pre-commit hook (gitleaks) plus a CI
+`secret-scan` job; lifecycle gating runs as git `commit-msg`/`pre-push`
+hooks plus the `validate-pr` workflow. Claude-side security guidance comes
+from the `security-guidance` plugin enabled in `settings.json`.
+
+**Manual invocation** (debugging or one-off runs only):
+```bash
+just lint                                # the same gate the hooks enforce
+# (with --no-plugin scaffolds the hook scripts live in .claude/hooks/)
+```
+
+Do not read hook scripts to understand their logic — descriptions above are sufficient. Only open a hook file if you are modifying it. To add a new hook, run the `add_hook` skill.

project_init/templates/base/dot_claude/rules/node.md

@@ -0,0 +1,17 @@
+---
+description: Node.js / Bun environment and tooling
+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "package.json", "bun.lockb"]
+alwaysApply: false
+---
+
+## Node.js environment
+
+Uses [`bun`](https://bun.sh). Never `npm` or `npx`.
+
+```bash
+bun install       # install deps
+bun run <script>  # run a package.json script
+bunx <package>    # run a binary (replaces npx)
+bun run lint      # lint
+bun test          # tests
+```

project_init/templates/base/dot_claude/rules/python.md

@@ -0,0 +1,25 @@
+---
+description: Python environment, tooling, and test conventions
+globs: ["**/*.py", "pyproject.toml", "uv.lock"]
+alwaysApply: false
+---
+
+## Python environment
+
+Uses [`uv`](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                           # install deps
+uv run <command>                  # run in the project venv
+uv run ruff check .               # lint
+uv run ruff format .              # format
+uv run pytest -n auto -q          # tests (parallel mode, requires pytest-xdist)
+uv run pytest -q --tb=short       # tests (single-threaded fallback)
+```
+
+**Test Optimization**: Use `pytest -n auto` in CI to parallelize tests across CPU cores (30-50% faster). Requires `pytest-xdist` in dev dependencies. See `ci.yml.tmpl` for a full optimized CI config.
+
+## Test conventions
+
+- One assertion per test; name: `test_<unit>_<scenario>`
+- External services (DB, API) use a real instance, not a mock

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

@@ -0,0 +1,15 @@
+# `.claude/scripts/`
+
+Helper scripts invoked by the user, by hooks, or by agents via the Bash tool. Prefer bash or python stdlib. Document each script with a one-line header comment.
+
+## Available scripts
+
+- **`install_hooks.sh`** — Symlink or copy git hooks from `.github/hooks/` to `.git/hooks/`
+- **`create_issue.sh`** — Create a typed GitHub issue and print its issue number
+- **`start_issue.sh`** — Create an issue branch, push it, and open a draft PR
+- **`create_nojira_pr.sh`** — Create or reuse a no-issue branch, push it, and open a draft PR
+- **`push_branch.sh`** — Push current branch with retry and remote-SHA verification (handles transient 5xx errors)
+- **`promote_review.sh`** — Mark a draft PR ready for review
+- **`monitor_pr.sh`** — Poll PR checks and optionally squash-merge with `--merge`
+- **`finish_pr.sh`** — Composite: push, mark ready, monitor checks/review, and merge
+- **`setup_github.sh`** — One-time GitHub repository governance setup (board fields, review settings; `--protect` applies baseline branch protection)