project-kit-cli 0.1.0__py3-none-any.whl

project_kit/__init__.py

@@ -0,0 +1,8 @@
+"""project-kit: define, plan and set up a project before handing off to Spec Kit."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("project-kit-cli")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0"

project_kit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from project_kit.cli import main
+
+sys.exit(main())

project_kit/agents.py

@@ -0,0 +1,81 @@
+"""AI coding agents project-kit can hand the terminal over to after ``init``.
+
+An agent is whatever reads the installed skills and runs ``/pk-start``. Today that is Claude
+Code only; supporting another one is a new entry in ``AGENTS``.
+"""
+
+import os
+import shutil
+import subprocess
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Agent:
+    id: str
+    name: str
+    executable: str
+    prompt: str  # what the agent is started with: the entry-point skill
+    install_hint: str
+    inside_env: str  # environment variable the agent sets in the shells it opens
+
+
+AGENTS = (
+    Agent(
+        id="claude",
+        name="Claude Code",
+        executable="claude",
+        prompt="/pk-start",
+        install_hint="https://claude.com/claude-code",
+        inside_env="CLAUDECODE",
+    ),
+)
+AGENT_IDS = tuple(a.id for a in AGENTS)
+
+
+def get_agent(agent_id: str) -> Agent:
+    return next(a for a in AGENTS if a.id == agent_id)
+
+
+def is_inside(agent: Agent, env: Mapping[str, str] | None = None) -> bool:
+    """True when we run from a shell opened by this agent: launching it again would nest."""
+    return bool((os.environ if env is None else env).get(agent.inside_env))
+
+
+def find_executable(agent: Agent) -> str | None:
+    return shutil.which(agent.executable)
+
+
+def choose(
+    ask: Callable[[str], str] | None = None,
+    out: Callable[[str], None] = print,
+) -> Agent | None:
+    """Ask which agent to open now. Enter takes the first one. ``None``: the user declines."""
+    out("\nOpen an AI agent now to continue with /pk-start?")
+    for n, agent in enumerate(AGENTS, 1):
+        out(f"  {n}) {agent.name}")
+    none = len(AGENTS) + 1
+    out(f"  {none}) No, I will do it myself")
+    try:
+        answer = (ask or input)("Choice [1]: ").strip()
+    except EOFError:  # no terminal attached: never launch anything
+        return None
+    if answer == "":
+        return AGENTS[0]
+    if answer.isdigit() and 1 <= int(answer) <= len(AGENTS):
+        return AGENTS[int(answer) - 1]
+    return None
+
+
+def launch(agent: Agent, root: Path, run: Callable[..., object] = subprocess.run) -> int:
+    """Run the agent in the current terminal, in ``root``, started with its entry skill.
+
+    Returns the agent's exit code; the terminal is inherited, so it is interactive.
+    """
+    exe = find_executable(agent)
+    if exe is None:
+        raise FileNotFoundError(agent.executable)
+    result = run([exe, agent.prompt], cwd=root, check=False)
+    return getattr(result, "returncode", 0)

project_kit/ai_attribution.py

@@ -0,0 +1,69 @@
+"""Keep AI assistants out of the commit history when the project asks for it.
+
+Two layers, because each assistant removes itself in its own way:
+
+* Claude Code has its own setting (``attribution`` in ``.claude/settings.json``), which stops
+  it from adding the co-author trailer and the "Generated with" line.
+* For any other assistant, and as a safety net, a ``commit-msg`` git hook strips co-author
+  trailers that name a known AI tool. It lives in ``.githooks/`` so it is versioned and the
+  whole team gets it; it is switched on with ``git config core.hooksPath .githooks``.
+
+Both only ever add what is missing; nothing the user wrote is overwritten.
+"""
+
+import contextlib
+import json
+import os
+from importlib.resources import files
+from pathlib import Path
+
+from project_kit.fsutil import atomic_write_text
+
+CLAUDE_SETTINGS = Path(".claude") / "settings.json"
+HOOK = Path(".githooks") / "commit-msg"
+HOOKS_PATH_COMMAND = "git config core.hooksPath .githooks"
+
+
+def configure_claude(root: Path) -> tuple[Path | None, str]:
+    """Make Claude Code stop signing commits and PRs. Returns (changed file or None, note)."""
+    path = root / CLAUDE_SETTINGS
+    data: dict = {}
+    if path.exists():
+        try:
+            loaded = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            return None, f"{CLAUDE_SETTINGS.as_posix()} is not valid JSON; left alone."
+        if not isinstance(loaded, dict):
+            return None, f"{CLAUDE_SETTINGS.as_posix()} is not a JSON object; left alone."
+        data = loaded
+
+    attribution = data.get("attribution")
+    attribution = dict(attribution) if isinstance(attribution, dict) else {}
+    if attribution.get("commit") == "" and attribution.get("pr") == "":
+        return None, ""
+    attribution["commit"] = ""
+    attribution["pr"] = ""
+    data["attribution"] = attribution
+    atomic_write_text(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    return CLAUDE_SETTINGS, ""
+
+
+def install_hook(root: Path) -> tuple[Path | None, str]:
+    """Copy the commit-msg hook unless the project already has one. Returns (new file, note)."""
+    dest = root / HOOK
+    if dest.exists():
+        return None, ""
+    script = (files("project_kit") / "assets" / "hooks" / "commit-msg").read_text("utf-8")
+    atomic_write_text(dest, script)
+    with contextlib.suppress(OSError):  # no executable bit on some filesystems (Windows)
+        os.chmod(dest, 0o755)
+    return HOOK, ""
+
+
+def hook_is_active(root: Path) -> bool:
+    """True if git is already pointed at ``.githooks`` in this repository."""
+    config = root / ".git" / "config"
+    if not config.is_file():
+        return False
+    text = config.read_text(encoding="utf-8", errors="replace")
+    return any("".join(line.split()).lower() == "hookspath=.githooks" for line in text.splitlines())

project_kit/approval.py

@@ -0,0 +1,36 @@
+"""Approval gates: record that the user signed off on a phase."""
+
+from pathlib import Path
+
+from project_kit.backlog import load_backlog
+from project_kit.config import load_config
+from project_kit.state import PHASES, State, StateError, load_state, save_state
+from project_kit.workflow import load_workflow
+
+
+def approve_phase(root: Path, phase: str) -> State:
+    """Record the approval of ``phase`` in the project state.
+
+    A gate refuses to open while an earlier enabled gate of ``workflow.yml`` is still open,
+    so the plan cannot be approved before the brief. The ``plan`` gate also refuses to open
+    unless the backlog on disk is valid, so an approval always refers to a backlog that
+    provisioning can use.
+    """
+    if phase not in PHASES:
+        raise StateError(f"Unknown phase {phase!r}. Phases: {', '.join(PHASES)}")
+    load_config(root)  # the project must have been initialised
+    state = load_state(root)
+    open_gates = load_workflow(root).open_gates_before(phase, state)
+    if open_gates:
+        names = ", ".join(f"{s.id} (/{s.skill})" for s in open_gates)
+        raise StateError(
+            f"Cannot approve {phase!r} yet: approve first {names}. "
+            "To skip a phase, set `enabled: false` on it in .project-kit/workflow.yml."
+        )
+    if phase == "plan":
+        load_backlog(root)
+    state.approve(phase)
+    if PHASES.index(phase) > PHASES.index(state.phase):
+        state.phase = phase
+    save_state(root, state)
+    return state

project_kit/assets/hooks/commit-msg

@@ -0,0 +1,14 @@
+#!/bin/sh
+# project-kit: keep AI assistants out of the commit history.
+# Removes "Co-authored-by:" trailers added by AI tools, and their "Generated with" lines.
+# Enable with:  git config core.hooksPath .githooks
+file="$1"
+tmp="$file.pk-tmp"
+grep -v -i -E \
+  -e '^co-authored-by:.*(claude|anthropic|copilot|openai|chatgpt|codex|gemini|cursor|aider|devin)' \
+  -e '^.*generated with.*(claude|copilot|codex|gemini|cursor)' \
+  "$file" > "$tmp"
+# grep exits 1 when nothing is left (an empty message): keep that case valid and silent.
+cat "$tmp" > "$file"
+rm -f "$tmp"
+exit 0

project_kit/assets/project/workflow.yml

@@ -0,0 +1,63 @@
+# project-kit workflow: the phases a project goes through before it is handed to Spec Kit.
+# Safe to edit by hand. Same idea as Spec Kit's workflow.yml: an ordered list of steps with
+# review gates, read by the skills to know what comes next.
+#
+#   gate: true       the phase ends with an explicit approval (`project-kit approve <id>`)
+#   enabled: false   skip the phase (small projects); later gates stop waiting for it
+#
+# The order is fixed and the ids are the ones project-kit knows; only `enabled`, `gate`,
+# `title` and `produces` are meant to be changed.
+schema_version: "1.0"
+workflow:
+  id: "project-kit"
+  name: "Project definition flow"
+  description: "From an idea to a provisioned repository and a Spec Kit handoff"
+
+steps:
+  - id: init
+    title: "Set up project-kit in the repository"
+    skill: pk-start
+    gate: false
+    produces:
+      - .project-kit/config.yml
+
+  - id: discover
+    title: "Define what the project is: problem, users, scope, constraints"
+    skill: pk-discover
+    gate: true
+    produces:
+      - docs/project/brief.md
+
+  - id: decide
+    title: "Decide the stack and the architecture"
+    skill: pk-decide
+    gate: true
+    produces:
+      - docs/adr/
+
+  - id: workflow
+    title: "Agree how the team will work: branches, reviews, quality gates"
+    skill: pk-workflow
+    gate: true
+    produces:
+      - docs/development-workflow.md
+
+  - id: plan
+    title: "Turn it all into phases, epics and a backlog"
+    skill: pk-plan
+    gate: true
+    produces:
+      - docs/project/roadmap.md
+      - .project-kit/backlog.json
+
+  - id: provision
+    title: "Create milestones, labels, branches, the Project and the issues"
+    skill: pk-provision
+    gate: false
+
+  - id: handoff
+    title: "Hand over to Spec Kit: constitution, then one spec per issue"
+    skill: pk-handoff
+    gate: true
+    produces:
+      - .project-kit/handoff/constitution-input.md

project_kit/assets/skills/pk-decide/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pk-decide
+description: Guide the user through the technical and architectural decisions of the project (repository structure, language, framework, package manager, data, auth, hosting, CI) and record each one as an ADR in docs/adr/. Use when the user wants to choose the stack or architecture, or to revisit a decision.
+---
+
+# pk-decide — phase 2
+
+Turn the brief into **decisions**: one ADR per decision, with the options considered and the
+reason for the choice. project-kit does not choose for the user; it makes the choice
+explicit, argued and written down. The ADRs feed the plan and, later, the Spec Kit
+constitution.
+
+Read `.project-kit/templates/interview.md` first and follow it. ADRs use
+`.project-kit/templates/adr.md`, are named `docs/adr/NNNN-short-title.md` (next free number)
+and can also be written by hand.
+
+## Inputs
+
+- `docs/project/brief.md`, especially "Constraints" and "Technical preferences already
+  stated". Preferences are proposals to confirm, not decisions.
+- Existing `docs/adr/*.md`: never decide twice. To change a decision, write a new ADR and mark
+  the old one `Superseded by ADR-NNNN`.
+
+## Steps
+
+1. **List the decisions this project needs**, from this checklist and from the brief; leave
+   out whatever does not apply (a command-line tool has no auth or hosting question):
+   - Repository: single repository, monorepo or several repositories; monolith or separate
+     services.
+   - Language and runtime; framework(s).
+   - Package manager and, for monorepos, workspace and build tooling (for example pnpm, npm,
+     yarn, uv, cargo workspaces, turborepo, nx).
+   - Data: storage, migrations, backups.
+   - Authentication and authorisation.
+   - API style and integrations with external services.
+   - Hosting, environments and deployment; CI.
+   - Testing approach and tools; observability.
+   - Anything the brief marks as legal or compliance-driven.
+2. **Show the list** and ask which ones are *critical* now (they block planning) and which
+   can wait. In "light" mode, only decide the critical ones. Deferred decisions are written
+   as `Status: Proposed` or left for a later `pk-decide`.
+3. **For each decision, one at a time:**
+   1. Ask the question in the interview format: options with pros and cons for *this*
+      project, a recommendation with the reason, and what depends on the answer. Use the
+      brief's constraints (team skills, budget, scale, compliance) as the drivers.
+   2. If a decision follows from an earlier one (a framework implies a language), do not ask:
+      state it and record it in the ADR as a consequence.
+   3. After the answer, write the ADR immediately (`Status: Accepted`, today's date) and tell
+      the user its path.
+4. **Check consistency** across ADRs: no contradictory choices (for example a package manager
+   that the chosen framework does not support). Raise any conflict as a question.
+5. **Present** the list of ADRs with their status and anything still undecided.
+6. **Approval gate.** When the critical ADRs are accepted and the user explicitly approves,
+   run `project-kit approve decide`.
+7. Run `project-kit status` and offer `pk-workflow` next: continue now, or stop here.
+
+## Rules
+
+- Do not decide on the user's behalf and do not present your recommendation as settled.
+- Never invent versions, prices or benchmarks; if a fact matters and you are not sure, say so
+  and mark it `[NEEDS CLARIFICATION]`.
+- Keep each ADR to one decision. Write them in the language of `config.yml`.
+- The `Status:` line matters: the handoff reads it to build the constitution.

project_kit/assets/skills/pk-discover/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pk-discover
+description: Interview the user about what the project is (problem, users, scope, constraints, success criteria) and write docs/project/brief.md; also clarifies an existing brief. Use when the user wants to define or describe the project, refine the brief, or after pk-start.
+---
+
+# pk-discover — phase 1
+
+Produce the **project brief**: what the project is and why, not how it is built. Technology is
+decided in the next phase (`pk-decide`). The brief can be written by this interview, filled
+in by hand from `.project-kit/templates/brief.md`, or both.
+
+Read `.project-kit/templates/interview.md` first and follow it: one question at a time with a
+recommended answer, save after every answer, mark gaps, approval only on an explicit "yes".
+
+## Inputs
+
+- `.project-kit/config.yml` (name, language) and `project-kit status`.
+- The description the user gave in `pk-start`, if any.
+- `docs/project/brief.md`, if it exists (hand-written or from an earlier session): ask only
+  about what is missing or partial.
+
+## Steps
+
+1. If `docs/project/brief.md` does not exist, create it from `.project-kit/templates/brief.md`
+   (replace `{{project_name}}`), and fill in whatever the user's description already answers.
+2. **Scan the brief** against these topics, marking each Clear / Partial / Missing:
+   - Problem and value: who hurts, how, what happens today without it.
+   - Users and stakeholders: roles, how they differ, who decides.
+   - Scope: the capabilities that must exist, grouped by theme, and what is explicitly out.
+   - Success criteria: how the user will know it worked, measurable where possible.
+   - Constraints: legal and compliance, budget, deadline, team size and skills, existing
+     systems, data residency.
+   - Data and integrations: what information is handled, which external services are needed.
+   - Risks and assumptions: what could make the project fail, what is being taken for granted.
+   - Terminology: words with an ambiguous meaning in this domain.
+3. **Interview** on the Partial and Missing topics, highest impact first, with a maximum of
+   **8 questions** in the first pass. Keep them at product level: if the user volunteers a
+   technology ("it will be in Next.js", "we use pnpm"), do not debate it; write it under
+   "Technical preferences already stated" for `pk-decide` and move on.
+4. If the user gave nothing to start from, begin with: "In a few sentences, what do you want
+   to build and who is it for?" and derive the next questions from the answer.
+5. **Check quality** before presenting: every goal and success criterion is verifiable, the
+   scope has an "out of scope" list, no statement names a technology as a requirement.
+6. **Present** a short summary of the brief and the markers still open.
+7. **Offer a clarification pass** (at most 5 more questions) before approval.
+8. **Approval gate.** When the user explicitly approves, set `**Status**: Approved` in the
+   brief and run `project-kit approve discover`.
+9. Run `project-kit status` and offer `pk-decide` next: continue now, or stop here.
+
+## Rules
+
+- Never invent users, numbers, deadlines or constraints. Unknown means a
+  `[NEEDS CLARIFICATION: ...]` marker or a labelled assumption.
+- Write the brief in the language of `config.yml`.
+- Do not run `project-kit approve discover` without an explicit "yes".
+- The brief is the user's document: if they edit it by hand between questions, re-read it
+  before the next change.

project_kit/assets/skills/pk-handoff/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: pk-handoff
+description: Hand the project over to Spec Kit: generate the constitution input from the project's decisions and set up Spec Kit (phase 6). Use when planning and provisioning are done and the user wants to start specifying features.
+---
+
+# pk-handoff — phase 6
+
+Prepare the text for `/speckit-constitution`, make sure Spec Kit is available, and point the
+user at the first specs. Spec Kit owns `.specify/`; project-kit never writes inside it.
+
+## Steps
+
+1. Ask the user whether the project has rules of its own that should be part of the
+   constitution (security, compliance, performance, team conventions). If so, write them as
+   a Markdown list to `.project-kit/handoff/constitution-extra.md`. That file is yours and
+   project-kit never overwrites it; it is added under "Project-specific rules".
+   Governance content only: no feature requests, no implementation tasks.
+2. Run `project-kit handoff --dry-run` and show the user what will be generated.
+3. Run `project-kit handoff`. It writes `.project-kit/handoff/constitution-input.md` and
+   reports the state of Spec Kit.
+4. If Spec Kit is not ready, explain what `project-kit handoff --install-speckit` would run
+   (it installs the `specify-cli` package with `uv` and runs `specify init --here`, which
+   merges Spec Kit's files into the repository). Only after an explicit "yes", run
+   `project-kit handoff --install-speckit --yes`.
+5. Tell the user to run, in this session:
+   `/speckit-constitution @.project-kit/handoff/constitution-input.md`
+   You cannot run that command for them.
+6. After the constitution exists, suggest mentioning `docs/project/`, `docs/adr/` and
+   `docs/development-workflow.md` in `CLAUDE.md` or `AGENTS.md`. Explain that from here Spec
+   Kit does the work: each backlog issue is one spec, and its text (description and acceptance
+   criteria) is the input of `/speckit-specify`; then `/speckit-clarify`, `/speckit-plan`,
+   `/speckit-tasks` and `/speckit-implement`. project-kit does not write specs.
+   Suggest the order: the issues of the first phase, by priority.
+7. When the user confirms the constitution is in place, run `project-kit approve handoff`.
+
+## Rules
+
+- `constitution-input.md` is regenerated every time. Do not edit it; put project-specific rules
+  in `constitution-extra.md`. If the user removes its `project-kit:managed` header the file is
+  theirs and is no longer regenerated.
+- Never modify anything inside `.specify/` by hand.
+- If project-kit warns about an untested Spec Kit version, tell the user, but continue: the
+  only thing project-kit depends on is the input file.

project_kit/assets/skills/pk-plan/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: pk-plan
+description: Turn the project's brief and decisions into a phased roadmap and a validated backlog (.project-kit/backlog.json). Use when the user wants to plan the project, break it into phases and epics, or revise the backlog before provisioning.
+---
+
+# pk-plan — phase 4
+
+Produce the project backlog and get it approved. Nothing is created in the provider here;
+that happens later, in the provision phase.
+
+## Inputs
+
+- `docs/project/brief.md` (scope, goals, constraints), `docs/adr/*.md` (decisions) and
+  `docs/development-workflow.md` (process). The plan is **derived** from them: scope becomes
+  epics, constraints and decisions become issues (repository setup, CI, the chosen
+  infrastructure) in the first phase.
+- **Run `project-kit status` first.** If an enabled earlier phase is not done, stop and tell
+  the user which skill to run (`/pk-discover`, `/pk-decide`, `/pk-workflow`). Do not
+  improvise a brief. If they want to skip a phase, they set `enabled: false` on it in
+  `.project-kit/workflow.yml`; only then plan without it, and say what is missing.
+- `.project-kit/config.yml` (project name, language, provider).
+- `.project-kit/templates/backlog.example.json`: follow its shape exactly.
+
+Write the backlog content in the language set in `config.yml`.
+
+## Steps
+
+1. **Draft the phases.** Each phase becomes a milestone and a value of the Phase field.
+   Keep them few and ordered by delivery (for example `v0.1 MVP`, `v0.2`, `v1.0`).
+2. **Draft the epics**, one per coherent delivery inside a phase.
+3. **Break each epic into issues** (`feature`, `bug`, `chore`, `adr`, `docs`) with `parent`
+   pointing at the epic. Give every `feature`, `bug` and `chore` concrete acceptance
+   criteria: observable statements a reviewer can tick, not tasks.
+4. **Set priority (P0–P3) and size (XS–XL)** on every issue. Prefer small issues; split
+   anything you would size XL unless it is an epic.
+5. **Write the file** to `.project-kit/backlog.json`.
+6. **Validate:** run `project-kit backlog validate`. Fix every problem it reports and run it
+   again until it passes. Never hand-edit your way around a validation error.
+7. **Present the plan** to the user: the summary printed by the validator plus, per phase, the
+   epics and their issues in a short list.
+8. **Approval gate.** Ask the user explicitly whether the plan is approved. If they ask for
+   changes, edit the backlog, validate again and present it again. Only when they say yes,
+   run `project-kit approve plan`.
+9. Optionally write `docs/project/roadmap.md` summarising the phases and epics for humans.
+10. Run `project-kit status` and offer `pk-provision` next: continue now, or stop here.
+
+## Rules
+
+- Do not run `project-kit approve plan` without an explicit "yes" from the user in this
+  conversation, and never approve on their behalf.
+- Ids are lowercase words joined by hyphens and stay stable once provisioned; do not rename
+  them when revising a backlog that was already provisioned.
+- Do not edit `.project-kit/state.json` by hand.
+- Each issue is meant to become a Spec Kit spec later: keep it about one deliverable, with
+  acceptance criteria a reviewer can verify.

project_kit/assets/skills/pk-provision/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pk-provision
+description: Create the milestones, labels, branches, GitHub Project and issues of the approved backlog in the repository's provider (phase 5). Use when the user wants to publish the plan to GitHub or to sync new backlog entries.
+---
+
+# pk-provision — phase 5
+
+Turn `.project-kit/backlog.json` into real milestones, labels, branches, a Project and issues.
+This writes to the provider, so nothing happens without the user's explicit consent.
+
+## Before starting
+
+- The plan must be approved: `project-kit approve plan` (the pk-plan skill does it).
+- Run `project-kit doctor`. `gh` must be logged in with the `repo` and `project` scopes.
+- The repository must already have a commit on its main branch.
+
+## Steps
+
+1. Run `project-kit provision --dry-run` and show the user the plan it prints: what will be
+   created, what already exists, and the note about branch protection.
+   - A `BLOCKING` line means nothing can be applied; explain it and help fix it.
+   - The `Project:` line says which GitHub Project will be used: one already linked to the
+     repository (`already exists`) or a new one. Tell the user and ask whether that is the one
+     they want. If not, rerun with `--project "<number or exact title>"` to use another
+     existing Project, or with a new title to create it.
+   - If it stops with "Several Projects match this repository", show the list, ask the user
+     which one (or a name for a new one) and rerun with `--project`. The choice is remembered.
+2. Ask the user whether to go ahead. Only after an explicit "yes" run
+   `project-kit provision --yes`. Never pass `--yes` without that consent.
+3. Report the result. Running the command again is always safe: it only creates what is
+   missing, never rewrites existing issues and never moves cards the user has moved.
+
+## Things to tell the user
+
+- Project **views** (Board, Roadmap, table) cannot be created through the API; they are made by
+  hand once in the Project's page.
+- Branch protection is only reported, never configured. On a private repository with a free
+  plan GitHub does not offer it; the branch rules are then followed by discipline.
+- If GitHub says the rate limit was reached, wait a minute and run the command again: the
+  progress is saved and the command resumes where it stopped.
+
+## Rules
+
+- Do not edit `.project-kit/state.json`; project-kit owns it.
+- To add work later, edit the backlog (pk-plan), validate it and run this again.

project_kit/assets/skills/pk-start/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pk-start
+description: Start here. Check that project-kit is ready in this repository, settle the basics (language, AI co-author policy) and ask whether to only initialise or to start defining the project right away. Use when the user has just run `project-kit init`, wants to begin a new project, or asks where to start.
+---
+
+# pk-start — phase 0
+
+Entry point of project-kit. The files are already in the repository (`project-kit init` put
+them there); this skill checks them, settles the basics and lets the user choose how far to go
+now. Nothing is created in GitHub or GitLab here.
+
+## Steps
+
+1. **Check the tools.** Run `project-kit doctor`.
+   - `FAIL` lines block: explain each hint and wait until it is fixed.
+   - `warn` lines are optional (`uv` and Spec Kit are only needed at the handoff phase).
+2. **Read the setup.** If `.project-kit/config.yml` is missing, tell the user to run
+   `project-kit init` in the terminal and stop. Otherwise read it back (project name,
+   provider, language, branches) and ask whether it is right. These are plain values that can
+   also be edited by hand. If the language is wrong, edit `language:` in the file.
+3. **AI co-author.** If `config.yml` says `ai_coauthor: true` and the user has not been
+   asked yet, ask whether AI assistants (Claude, Copilot...) should appear as co-authors of
+   commits and pull requests. If they do not want it:
+   - set `ai_coauthor: false` in `config.yml` and run `project-kit init`: it makes Claude
+     Code stop signing (`attribution` in `.claude/settings.json`) and installs a
+     `commit-msg` hook that strips the co-author trailer of any other assistant;
+   - ask before running `git config core.hooksPath .githooks`, which switches the hook on for
+     this clone. Each teammate runs that command once.
+4. **Ask how far to go now.** Offer exactly these two options:
+
+   | Option | What happens |
+   |--------|--------------|
+   | **A. Only initialise** | Stop here. The user comes back later with `/pk-discover` |
+   | **B. Start defining the project** | Continue now with the discovery interview |
+
+   Recommend B unless the user said they are in a hurry.
+5. **If A:** run `project-kit status`, show it, and explain that `/pk-discover` is next. Done.
+6. **If B:** ask for a short description of the project in the user's own words, a few
+   sentences, a pasted note or "nothing yet, ask me". Then follow the `pk-discover` skill
+   (`.claude/skills/pk-discover/SKILL.md`) using that description as the starting point.
+
+## Rules
+
+- `project-kit init` never overwrites existing files, so it is safe to run again.
+- Do not edit `.project-kit/state.json` by hand; project-kit owns it.
+- The phases are listed in `.project-kit/workflow.yml`; the user may disable some of them
+  (`enabled: false`) for a small project. `project-kit status` shows what is left.

project_kit/assets/skills/pk-workflow/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: pk-workflow
+description: Agree how the team will work (branches, pull requests, reviews, commits, versioning, quality gates, definition of done) and write docs/development-workflow.md. Use when the user wants to define the development process or change it.
+---
+
+# pk-workflow — phase 3
+
+Record **how the project is developed**: the process that the plan, the provisioned
+repository and the Spec Kit constitution will all follow. It is written in
+`docs/development-workflow.md` (template: `.project-kit/templates/development-workflow.md`),
+by this interview or by hand.
+
+Read `.project-kit/templates/interview.md` first and follow it.
+
+## Inputs
+
+- `docs/project/brief.md` and `docs/adr/*.md`: team size, repository structure, package
+  manager and CI already decided there are not asked again; link them.
+- `.project-kit/config.yml`: branch names (`main`, `release`, `develop`) and provider.
+- The PR and issue templates that `project-kit init` put in `.project-kit/templates/github/`.
+
+## Topics (maximum 8 questions; propose a default for each and ask only what matters)
+
+- **Team and review:** how many people, who approves, how many approvals.
+- **Branches:** keep `main` / `release` / `develop` with one branch per spec, or a lighter
+  model (only `main`) for a small project. Name the types of working branch.
+- **Merging:** merge strategy per branch, who may merge, tags and releases.
+- **Commits and versions:** commit convention, versioning scheme.
+- **Repository tooling:** formatters, linters, git hooks, which follow from the ADRs.
+- **Quality gates:** what must be green before merging (tests, lint, types, security scan).
+- **Definition of Done.**
+- **Git hosting rules:** branch protection availability on the hosting plan.
+
+## Steps
+
+1. Create `docs/development-workflow.md` from the template if it does not exist; fill in what
+   the ADRs and config already settle.
+2. Interview on the rest, then write the answers into the document after each one.
+3. If the user changes branch names or drops `release`/`develop`, edit `branches:` in
+   `.project-kit/config.yml` too (it must keep three different names), and tell the user.
+4. **Present** the document and the open markers; offer a clarification pass.
+5. **Approval gate.** On an explicit "yes", set `**Status**: Approved` and run
+   `project-kit approve workflow`.
+6. Run `project-kit status` and offer `pk-plan` next: continue now, or stop here.
+
+## Rules
+
+- Do not configure anything in the provider here: branches and protection are created by
+  `pk-provision`, after the plan.
+- Do not repeat technical decisions; link the ADR.
+- Write in the language of `config.yml`.