project-init 0.3.0__py3-none-any.whl

project_init/templates/base/dot_github/ISSUE_TEMPLATE/test.yml

@@ -0,0 +1,90 @@
+name: Test
+description: Missing or insufficient test coverage
+labels: [test]
+body:
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      options: [high, medium, low]
+    validations:
+      required: true
+  - type: input
+    id: area
+    attributes:
+      label: Area
+      placeholder: frontend, backend, docs, devops, product
+    validations:
+      required: true
+  - type: dropdown
+    id: size
+    attributes:
+      label: Size
+      options: [XS, S, M, L, XL]
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: What behavior needs coverage?
+      description: Describe the behavior, template, script, or workflow that needs tests.
+    validations:
+      required: true
+  - type: textarea
+    id: risk
+    attributes:
+      label: Risk
+      description: What regression or bug could slip through without this test?
+    validations:
+      required: true
+  - type: textarea
+    id: approach
+    attributes:
+      label: Suggested approach
+      placeholder: "Unit test, scaffold-output diff, CLI test, workflow validation..."
+  - type: textarea
+    id: references
+    attributes:
+      label: References
+      description: Related issues, PRs, ADRs, docs, designs, or external links.
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies
+      description: Blocked-by, parent, or follow-up relationships.
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      placeholder: |
+        - [ ] ...
+    validations:
+      required: true
+  - type: dropdown
+    id: agent_ready
+    attributes:
+      label: Agent ready
+      description: Can an AI agent implement this without human clarification?
+      options: ["Yes", "No"]
+      default: 1
+  - type: dropdown
+    id: confidence
+    attributes:
+      label: Confidence
+      description: How well-understood is the scope and approach?
+      options: [high, medium, low, unknown]
+      default: 3
+  - type: textarea
+    id: ready
+    attributes:
+      label: Definition of Ready
+      placeholder: What must be true before implementation starts?
+    validations:
+      required: true
+  - type: textarea
+    id: done
+    attributes:
+      label: Definition of Done
+      placeholder: What must be true before this can close?
+    validations:
+      required: true

project_init/templates/base/dot_github/copilot-instructions.md.tmpl

@@ -0,0 +1,25 @@
+# GitHub Copilot Instructions — {{project_name}}
+
+Canonical agent rules: [AGENTS.md](../AGENTS.md) | Workflow: [.claude/project-init.md](../.claude/project-init.md)
+
+## Issue & project tracking
+
+- Tracking system: **GitHub Projects** (kanban board) + **GitHub Issues** (tickets)
+- Create issues: load the `create_issue` skill and use `.claude/scripts/create_issue.sh`; it handles metadata gathering, priority labels, and acceptance criteria
+- Board cards move automatically via `board-automation.yml` — no manual updates needed
+- Use a dedicated branch for each issue; format it as `<issue_type>/<project_abbr>-<issue_number>-<slug>`, e.g. `feat/PI-42-add-auth`; no direct commits to `main`
+- Issue and PR names use a project key: `<PROJECT-KEY>-<issue-number>`, e.g. `PI-42`
+- PR titles must follow Conventional Commits with the issue key as scope: `type(PROJECT-123): description` where type ∈ {feat, fix, chore, docs, test}, e.g. `feat(PI-42): Add OAuth login`
+- For small no-issue PRs omit the scope: `type: description`, e.g. `fix: Fix typo`
+- PR body must still include the GitHub numeric reference `Closes #N` — auto-closes issue and moves board card to Done on merge (skip for no-issue PRs)
+- Draft PRs are opened immediately when work starts, not when done
+- When asked to push/finish a PR, load the `github_workflow` skill for the full lifecycle and review-cycle protocol.
+- No direct commits to `main`
+
+## Key rules
+
+- Write failing tests before implementation (TDD)
+- No secrets in code — use `os.environ` or `.env` (gitignored)
+{{#if lint_command}}- `just lint` must pass before closing a task (`just --list` shows all recipes)
+{{/if}}- Prefer deterministic bash/python over LLM calls for hooks and scripts
+- Permanent decisions → `.claude/docs/adr/`; exploratory notes → `.claude/vault/`; reusable facts → `.claude/memory/`

project_init/templates/base/dot_github/hooks/commit-msg

@@ -0,0 +1,52 @@
+#!/bin/bash
+# commit-msg hook: validate commit message format before push.
+# Install: .claude/scripts/install-hooks.sh (runs automatically)
+#
+# Canonical format (Conventional Commits, ADR-006):
+#   feat(PI-42): Add OAuth login        (issue-linked — key as scope)
+#   fix: Fix typo in README             (no linked issue)
+#   feat(PI-9)!: Drop python 3.10       (breaking change)
+#
+# Legacy format still accepted during transition:
+#   [PI-42][feat] Add OAuth login
+#   [nojira][fix] Fix typo in README
+#
+# Any uppercase project key works: PI-, APP-, API-, WEB-, etc.
+# Types: feat  fix  chore  docs  test
+
+MSG=$(cat "$1")
+
+# Allow merge commits, fixups, reverts, and WIP
+if echo "$MSG" | grep -qE '^(Merge|Revert|fixup!|squash!|WIP)'; then
+  exit 0
+fi
+
+# Allow GitHub co-author trailers (multi-line commits)
+FIRST_LINE=$(echo "$MSG" | head -1)
+
+# Conventional Commits with optional issue-key scope (canonical)
+if echo "$FIRST_LINE" | grep -qE '^(feat|fix|chore|docs|test)(\([A-Z][A-Z0-9]{1,9}-[0-9]+\))?!?: .+'; then
+  exit 0
+fi
+
+# Legacy bracket format (transition)
+if echo "$FIRST_LINE" | grep -qE '^\[([A-Z][A-Z0-9]{1,9}-[0-9]+|nojira)\]\[(feat|fix|chore|docs|test)\] .+'; then
+  exit 0
+fi
+
+echo "" >&2
+echo "ERROR: commit message format invalid." >&2
+echo "" >&2
+echo "Required: <type>(<PROJECT>-<n>): Short description" >&2
+echo "      or: <type>: Short description        (no linked issue)" >&2
+echo "" >&2
+echo "Types: feat  fix  chore  docs  test" >&2
+echo "" >&2
+echo "Examples:" >&2
+echo "  feat(PI-42): Add OAuth login" >&2
+echo "  fix(APP-99): Handle null pointer in auth" >&2
+echo "  chore: Bump dev dependency" >&2
+echo "" >&2
+echo "Your message: $FIRST_LINE" >&2
+echo "" >&2
+exit 1

project_init/templates/base/dot_github/hooks/pre-commit

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# pre-commit hook: scan staged changes for secrets with gitleaks (ADR-007).
+# Install: .claude/scripts/install_hooks.sh
+#
+# Fail-open by design: if gitleaks is not installed the hook warns and lets
+# the commit through — the CI secret-scan job is the hard backstop that
+# scans full history and blocks the merge.
+
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo "WARNING: gitleaks not installed — skipping local secret scan." >&2
+  echo "  CI will still scan; install for fast local feedback:" >&2
+  echo "    https://github.com/gitleaks/gitleaks#installing" >&2
+  exit 0
+fi
+
+exec gitleaks git --pre-commit --staged --redact --no-banner --verbose

project_init/templates/base/dot_github/hooks/pre-push

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Pre-push hook: lifecycle gate (ADR-007).
+#   1. Prevent direct pushes to main/master.
+#   2. Enforce a branch type prefix — (feat|fix|chore|docs|test)/<slug> —
+#      the same rule as dag_workflow.py's _BRANCH_RE. Full issue-key
+#      validation (<type>/<KEY>-<n>-<slug>) runs in CI via validate-pr.yml,
+#      where the linked issue can actually be checked.
+# Install: .claude/scripts/install_hooks.sh
+
+set -e
+
+ZERO_SHA="0000000000000000000000000000000000000000"
+
+while read local_ref local_sha remote_ref remote_sha; do
+  # Branch deletions are always allowed (cleaning up misnamed branches).
+  if [[ "$local_sha" == "$ZERO_SHA" ]]; then
+    continue
+  fi
+
+  # Only gate branch refs — tags pass through.
+  if [[ "$remote_ref" != refs/heads/* ]]; then
+    continue
+  fi
+  branch_name="${remote_ref#refs/heads/}"
+
+  if [[ "$branch_name" == "main" || "$branch_name" == "master" ]]; then
+    echo "❌ ERROR: Direct push to main/master is not allowed"
+    echo ""
+    echo "To contribute:"
+    echo "  1. Create a new branch with the project key: git checkout -b <issue_type>/<project_abbr>-<issue_number>-<slug>"
+    echo "  2. Make your changes and push: .claude/scripts/push_branch.sh"
+    echo "  3. Open a PR on GitHub"
+    echo ""
+    echo "For more details, see .claude/project-init.md"
+    exit 1
+  fi
+
+  if ! echo "$branch_name" | grep -qE '^(feat|fix|chore|docs|test)/[A-Za-z0-9._/-]+$'; then
+    echo "❌ ERROR: branch '$branch_name' does not follow the lifecycle naming convention"
+    echo ""
+    echo "Enforced here: a type prefix — (feat|fix|chore|docs|test)/<slug>"
+    echo "Full convention (issue key validated in CI): <issue_type>/<project_abbr>-<issue_number>-<slug>"
+    echo "  Issue-linked:  feat/PI-42-add-oauth-login"
+    echo "  No issue:      chore/nojira-bump-dev-dependency"
+    echo ""
+    echo "Use .claude/scripts/start_issue.sh or create_nojira_pr.sh to create branches."
+    exit 1
+  fi
+done
+
+exit 0

project_init/templates/base/dot_github/pull_request_template.md

@@ -0,0 +1,22 @@
+<!-- PR Title Format: type(PROJECT-123): description  OR  type: description (no linked issue) -->
+<!-- Valid types: feat | fix | chore | docs | test -->
+
+## Summary
+
+Closes #<!-- issue number -->
+
+<!-- 2-4 bullet points describing what changed and why -->
+
+-
+
+## Changes
+
+<!-- List the key files/components changed -->
+
+-
+
+## Test plan
+
+- [ ] Tests pass
+- [ ] Lint passes
+- [ ] Manual smoke test (describe what you clicked/ran)

project_init/templates/base/dot_github/workflows/board-automation.yml

@@ -0,0 +1,232 @@
+name: Board automation
+
+# Syncs issue and PR lifecycle state to GitHub Projects v2.
+#
+# Setup:
+#   1. Create a PAT with Projects access.
+#   2. Store it as PROJECT_TOKEN.
+#   3. Set PROJECT_NUMBER to the target project number.
+#   4. Optional project fields: Status, Priority, Area, Size.
+
+on:
+  issues:
+    types: [opened, edited, reopened, labeled, unlabeled]
+  pull_request:
+    types: [opened, ready_for_review, closed]
+
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+
+jobs:
+  board-sync:
+    runs-on: ubuntu-24.04
+    env:
+      GH_TOKEN: ${{ secrets.PROJECT_TOKEN }}
+      OWNER: ${{ github.repository_owner }}
+      REPO_NAME: ${{ github.event.repository.name }}
+      PROJECT_NUMBER: 1
+
+    steps:
+      - name: Determine issue and status
+        id: context
+        env:
+          EVENT: ${{ github.event_name }}
+          ACTION: ${{ github.event.action }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+          PR_MERGED: ${{ github.event.pull_request.merged }}
+        run: |
+          set -euo pipefail
+
+          status="skip"
+          issue=""
+
+          if [ "$EVENT" = "issues" ]; then
+            issue="$ISSUE_NUMBER"
+            if [ "$ACTION" = "opened" ] || [ "$ACTION" = "reopened" ]; then
+              status="To Do"
+            else
+              status="metadata"
+            fi
+          elif [ "$EVENT" = "pull_request" ] && [ "$ACTION" = "opened" ]; then
+            issue=$(printf '%s\n' "$PR_BODY" | grep -oiP '(closes|fixes|resolves)\s+#\K[0-9]+' | head -1 || true)
+            status="In Progress"
+          elif [ "$EVENT" = "pull_request" ] && [ "$ACTION" = "ready_for_review" ]; then
+            issue=$(printf '%s\n' "$PR_BODY" | grep -oiP '(closes|fixes|resolves)\s+#\K[0-9]+' | head -1 || true)
+            status="In Review"
+          elif [ "$EVENT" = "pull_request" ] && [ "$ACTION" = "closed" ] && [ "$PR_MERGED" = "true" ]; then
+            issue=$(printf '%s\n' "$PR_BODY" | grep -oiP '(closes|fixes|resolves)\s+#\K[0-9]+' | head -1 || true)
+            status="Done"
+          fi
+
+          echo "issue=$issue" >> "$GITHUB_OUTPUT"
+          echo "status=$status" >> "$GITHUB_OUTPUT"
+
+      - name: Sync project item fields
+        if: steps.context.outputs.issue != '' && steps.context.outputs.status != 'skip'
+        env:
+          ISSUE_NUM: ${{ steps.context.outputs.issue }}
+          TARGET_STATUS: ${{ steps.context.outputs.status }}
+        run: |
+          set -euo pipefail
+
+          PROJECT_DATA=$(gh api graphql -f query='
+            query($owner: String!, $number: Int!) {
+              user(login: $owner) {
+                projectV2(number: $number) {
+                  id
+                  fields(first: 50) {
+                    nodes {
+                      ... on ProjectV2SingleSelectField {
+                        id
+                        name
+                        options { id name }
+                      }
+                    }
+                  }
+                  items(first: 100) {
+                    nodes {
+                      id
+                      content {
+                        ... on Issue { number }
+                      }
+                    }
+                  }
+                }
+              }
+              organization(login: $owner) {
+                projectV2(number: $number) {
+                  id
+                  fields(first: 50) {
+                    nodes {
+                      ... on ProjectV2SingleSelectField {
+                        id
+                        name
+                        options { id name }
+                      }
+                    }
+                  }
+                  items(first: 100) {
+                    nodes {
+                      id
+                      content {
+                        ... on Issue { number }
+                      }
+                    }
+                  }
+                }
+              }
+            }' -f owner="$OWNER" -F number="$PROJECT_NUMBER")
+
+          PROJECT=$(echo "$PROJECT_DATA" | jq -c '.data.user.projectV2 // .data.organization.projectV2 // empty')
+          PROJECT_ID=$(echo "$PROJECT" | jq -r '.id // empty')
+
+          if [ -z "$PROJECT_ID" ]; then
+            echo "Skipping project sync: project not found or PROJECT_TOKEN lacks access"
+            exit 0
+          fi
+
+          ITEM_ID=$(echo "$PROJECT" | jq -r --argjson n "$ISSUE_NUM" '(.items.nodes // [])[] | select(.content.number == $n) | .id')
+
+          if [ -z "$ITEM_ID" ]; then
+            echo "Issue #$ISSUE_NUM not found on board; adding it first"
+            ISSUE_NODE_ID=$(gh api graphql -f query='
+              query($owner: String!, $repo: String!, $number: Int!) {
+                repository(owner: $owner, name: $repo) {
+                  issue(number: $number) { id }
+                }
+              }' -f owner="$OWNER" -f repo="$REPO_NAME" -F number="$ISSUE_NUM" | jq -r '.data.repository.issue.id')
+
+            ITEM_ID=$(gh api graphql -f query='
+              mutation($project: ID!, $content: ID!) {
+                addProjectV2ItemById(input: { projectId: $project, contentId: $content }) {
+                  item { id }
+                }
+              }' -f project="$PROJECT_ID" -f content="$ISSUE_NODE_ID" | jq -r '.data.addProjectV2ItemById.item.id')
+          fi
+
+          ISSUE_DATA=$(gh issue view "$ISSUE_NUM" -R "$OWNER/$REPO_NAME" --json labels,body)
+          parse_body_field() {
+            local heading="$1"
+            local body="$2"
+            printf '%s\n' "$body" | awk -v h="$heading" '
+              BEGIN { in_section = 0 }
+              $0 ~ "^[[:space:]]*###[[:space:]]+" h "[[:space:]]*$" { in_section = 1; next }
+              in_section && /^[[:space:]]*$/ { next }
+              in_section { print; exit }
+            '
+          }
+          BODY=$(echo "$ISSUE_DATA" | jq -r '.body')
+          PRIORITY=$(parse_body_field "Priority" "$BODY")
+          SIZE=$(parse_body_field "Size" "$BODY")
+          AGENT_READY=$(parse_body_field "Agent ready" "$BODY")
+          CONFIDENCE=$(parse_body_field "Confidence" "$BODY")
+          TYPE_LABEL=$(echo "$ISSUE_DATA" | jq -r '[.labels[].name | select(. == "feature" or . == "bug" or . == "chore" or . == "documentation" or . == "test")][0] // empty')
+          parse_area() {
+            local body="$1"
+            local area
+
+            area=$(printf '%s\n' "$body" | sed -n 's/^- Area: //Ip' | head -1)
+            if [ -n "$area" ]; then
+              printf '%s\n' "$area"
+              return 0
+            fi
+
+            printf '%s\n' "$body" | awk '
+              BEGIN { in_area = 0 }
+              /^[[:space:]]*###[[:space:]]+Area[[:space:]]*$/ {
+                in_area = 1
+                next
+              }
+              in_area && /^[[:space:]]*$/ { next }
+              in_area {
+                print
+                exit
+              }
+            '
+          }
+          AREA=$(parse_area "$(echo "$ISSUE_DATA" | jq -r '.body')")
+
+          update_single_select() {
+            local field_name="$1"
+            local option_name="$2"
+            [ -n "$option_name" ] || return 0
+
+            local field_id
+            local option_id
+            field_id=$(echo "$PROJECT" | jq -r --arg f "$field_name" '(.fields.nodes // [])[] | select(.name == $f) | .id')
+            if [ -z "$field_id" ]; then
+              echo "Skipping missing project field: $field_name"
+              return 0
+            fi
+
+            option_id=$(echo "$PROJECT" | jq -r --arg f "$field_name" --arg o "$option_name" '(.fields.nodes // [])[] | select(.name == $f) | (.options // [])[] | select(.name == $o) | .id')
+            if [ -z "$option_id" ]; then
+              echo "Skipping missing project option: $field_name=$option_name"
+              return 0
+            fi
+
+            gh api graphql -f query='
+              mutation($project: ID!, $item: ID!, $field: ID!, $option: String!) {
+                updateProjectV2ItemFieldValue(input: {
+                  projectId: $project
+                  itemId: $item
+                  fieldId: $field
+                  value: { singleSelectOptionId: $option }
+                }) { projectV2Item { id } }
+              }' -f project="$PROJECT_ID" -f item="$ITEM_ID" -f field="$field_id" -f option="$option_id"
+          }
+
+          if [ "$TARGET_STATUS" != "metadata" ]; then
+            update_single_select "Status" "$TARGET_STATUS"
+          fi
+          update_single_select "Priority"    "$PRIORITY"
+          update_single_select "Area"        "$AREA"
+          update_single_select "Size"        "$SIZE"
+          update_single_select "Agent ready" "$AGENT_READY"
+          update_single_select "Confidence"  "$CONFIDENCE"
+          update_single_select "Type"        "$TYPE_LABEL"
+
+          echo "Synced issue #$ISSUE_NUM to GitHub Project metadata fields"