project-kit-cli 0.1.0__tar.gz → 0.2.0__tar.gz

project_kit_cli-0.2.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: project-kit-cli
+Version: 0.2.0
+Summary: Project definition and dev-workflow kit that hands off to Spec Kit
+Keywords: project-management,spec-kit,claude-code,workflow,github
+Author: Miguel Tomás
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/miguelmatg/project-kit
+Project-URL: Issues, https://github.com/miguelmatg/project-kit/issues
+Description-Content-Type: text/markdown
+
+# project-kit
+
+[![PyPI](https://img.shields.io/pypi/v/project-kit-cli)](https://pypi.org/project/project-kit-cli/)
+[![License: MIT](https://img.shields.io/pypi/l/project-kit-cli)](https://github.com/miguelmatg/project-kit/blob/main/LICENSE)
+
+**Everything that happens before the first line of code.** project-kit guides you, with an AI
+agent, through defining a project, deciding its stack and architecture, agreeing how the team
+works and planning the backlog. It then sets up GitHub and hands the project over to
+[Spec Kit](https://github.com/github/spec-kit), which specifies and builds each feature.
+
+```
+idea ──▶ brief ──▶ decisions (ADRs) ──▶ workflow ──▶ backlog ──▶ GitHub ──▶ Spec Kit
+         /pk-discover   /pk-decide       /pk-workflow   /pk-plan   /pk-provision  /pk-handoff
+```
+
+The conversations run in your AI agent (today, [Claude Code](https://claude.com/claude-code)) as
+`/pk-…` skills: one question at a time, a recommended answer for each, and everything written to
+documents in your repository. Every phase ends with your approval, and every document can be
+written by hand instead.
+
+> **Status: alpha.** It works end to end on GitHub with Claude Code. GitLab and other agents are
+> planned.
+
+## Requirements
+
+- [uv](https://docs.astral.sh/uv/) (it also fetches Python 3.12+ if you do not have it)
+- `git`
+- [Claude Code](https://claude.com/claude-code), to run the guided phases
+- [`gh`](https://cli.github.com/), logged in with the `repo` and `project` scopes
+  (`gh auth login`, then `gh auth refresh -s project`), to create things on GitHub
+
+`project-kit doctor` checks all of this for you. Spec Kit is installed for you at the end, if
+you want it.
+
+## Install
+
+```bash
+uv tool install project-kit-cli      # installs the `project-kit` command
+uv tool upgrade project-kit-cli      # later, to update the program
+```
+
+The package is called `project-kit-cli`; the command is `project-kit`. To try it without
+installing: `uvx --from project-kit-cli project-kit help`.
+
+**Updating a project.** `init` copies the skills and templates into your repository and never
+overwrites them, so a new version of the program does not change a project that already exists.
+Run `project-kit upgrade` inside it to see what is out of date, and `project-kit upgrade --apply`
+to bring it up to date. Files you edited are never overwritten; see
+[upgrading](https://github.com/miguelmatg/project-kit/blob/main/docs/upgrade.md).
+
+## Quick start
+
+In your repository, new or existing:
+
+```bash
+cd my-project
+project-kit init
+```
+
+`init` copies the skills and templates into the repository and then offers to open Claude Code
+right there, already running `/pk-start` (press Enter to accept). `/pk-start` asks whether to
+**only initialise** or to **start defining the project now**, and after every phase it asks
+whether to continue or stop. You can leave at any point and come back later:
+
+```bash
+project-kit status     # where you are and what comes next
+project-kit help       # a visual guide to the flow and the commands
+```
+
+## The phases
+
+| # | Skill | What it does | Produces |
+|---|---|---|---|
+| 0 | `/pk-start` | Checks your setup and lets you choose: only initialise, or start now | `.project-kit/` |
+| 1 | `/pk-discover` | Interviews you about the project: problem, users, scope, constraints | `docs/project/brief.md` |
+| 2 | `/pk-decide` | Guides the technical decisions: monolith or monorepo, language, package manager, data, auth, hosting | `docs/adr/*.md` |
+| 3 | `/pk-workflow` | Agrees how the team works: branches, reviews, quality gates | `docs/development-workflow.md` |
+| 4 | `/pk-plan` | Derives phases, epics and a backlog from all of the above | `docs/project/roadmap.md`, `.project-kit/backlog.json` |
+| 5 | `/pk-provision` | Creates milestones, labels, branches, the GitHub Project and the issues | GitHub |
+| 6 | `/pk-handoff` | Prepares the Spec Kit constitution; each issue becomes a spec | `.project-kit/handoff/constitution-input.md` |
+
+Each phase ends with an explicit approval (`project-kit approve <phase>`), and a phase cannot be
+approved while an earlier one is still open. The phases are listed in `.project-kit/workflow.yml`;
+for a small project, switch one off with `enabled: false`.
+
+To fill a document by hand instead, copy the matching template from `.project-kit/templates/`
+(`brief.md`, `adr.md`, `development-workflow.md`). The skills read what is already there and only
+ask about what is missing.
+
+## Existing repositories and Projects
+
+`init` never overwrites a file, so it is safe in a repository that already has code, documents or
+a `.claude/` folder. Before creating a GitHub Project, `provision` looks at the ones already
+linked to the repository: with one it asks whether to use it, with several it lists them, and
+with none it asks for a name. Use `--project <number or title>` to choose without being asked.
+It never rewrites issues that already exist, and re-running it is always safe.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `project-kit init` | Install the skills, templates and workflow in the current directory |
+| `project-kit status` | Show the phases and what comes next |
+| `project-kit upgrade [--apply] [--adopt] [--diff]` | Update the skills and templates a project already has |
+| `project-kit help` | Show a visual guide (also what plain `project-kit` prints) |
+| `project-kit doctor` | Check that git, gh, uv and Spec Kit are available |
+| `project-kit approve <phase>` | Record your sign-off of a phase |
+| `project-kit backlog validate` | Validate `.project-kit/backlog.json` |
+| `project-kit provision [--dry-run] [--project X]` | Create milestones, branches, the Project and issues on GitHub |
+| `project-kit handoff [--install-speckit]` | Generate the Spec Kit constitution input |
+
+Useful `init` options: `--project-name`, `--language` (language of the generated documents),
+`--agent claude|none` (open the agent or not) and `--ai-coauthor keep|remove`.
+
+## AI co-author
+
+`init` asks whether AI assistants may appear as co-authors of your commits and pull requests. If
+not, it configures Claude Code to stop signing them and installs a `commit-msg` hook that strips
+the co-author trailer of other assistants. Switch the hook on once per clone with
+`git config core.hooksPath .githooks`.
+
+## After the handoff
+
+`/pk-handoff` leaves a text file for Spec Kit's constitution and tells you the next step:
+
+```
+/speckit-constitution @.project-kit/handoff/constitution-input.md
+```
+
+From there Spec Kit does the work. Each issue of the backlog is one spec: its text is the input of
+`/speckit-specify`, followed by `/speckit-clarify`, `/speckit-plan`, `/speckit-tasks` and
+`/speckit-implement`. project-kit never writes inside `.specify/` and does not write specs.
+
+The constitution is generated from your own rules: the branch pattern and merge strategy you agreed,
+the decisions on record, and an index of where each kind of rule lives (including the GitHub
+Project used for tasks). Once the constitution is written, `project-kit approve handoff` deletes
+the temporary input files; from then on the constitution is the single source.
+
+## What it adds to your repository
+
+```
+.project-kit/          config.yml, state.json, workflow.yml, templates/, handoff/
+.claude/skills/pk-*/   the skills
+docs/project/          brief.md, roadmap.md        (created by the phases)
+docs/adr/              one file per decision       (created by the phases)
+.githooks/commit-msg   only if you removed the AI co-author
+```
+
+## Documentation
+
+More detail lives in the repository (in Spanish):
+[design](https://github.com/miguelmatg/project-kit/blob/main/docs/design.md),
+[backlog schema](https://github.com/miguelmatg/project-kit/blob/main/docs/backlog-schema.md),
+[provisioning](https://github.com/miguelmatg/project-kit/blob/main/docs/provisioning.md) and
+[Spec Kit handoff](https://github.com/miguelmatg/project-kit/blob/main/docs/handoff.md).
+
+## Feedback
+
+Ideas and bug reports are welcome as
+[issues](https://github.com/miguelmatg/project-kit/issues). Pull requests are not accepted; see
+[CONTRIBUTING](https://github.com/miguelmatg/project-kit/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/miguelmatg/project-kit/blob/main/LICENSE)

project_kit_cli-0.2.0/README.md

@@ -0,0 +1,165 @@
+# project-kit
+
+[![PyPI](https://img.shields.io/pypi/v/project-kit-cli)](https://pypi.org/project/project-kit-cli/)
+[![License: MIT](https://img.shields.io/pypi/l/project-kit-cli)](https://github.com/miguelmatg/project-kit/blob/main/LICENSE)
+
+**Everything that happens before the first line of code.** project-kit guides you, with an AI
+agent, through defining a project, deciding its stack and architecture, agreeing how the team
+works and planning the backlog. It then sets up GitHub and hands the project over to
+[Spec Kit](https://github.com/github/spec-kit), which specifies and builds each feature.
+
+```
+idea ──▶ brief ──▶ decisions (ADRs) ──▶ workflow ──▶ backlog ──▶ GitHub ──▶ Spec Kit
+         /pk-discover   /pk-decide       /pk-workflow   /pk-plan   /pk-provision  /pk-handoff
+```
+
+The conversations run in your AI agent (today, [Claude Code](https://claude.com/claude-code)) as
+`/pk-…` skills: one question at a time, a recommended answer for each, and everything written to
+documents in your repository. Every phase ends with your approval, and every document can be
+written by hand instead.
+
+> **Status: alpha.** It works end to end on GitHub with Claude Code. GitLab and other agents are
+> planned.
+
+## Requirements
+
+- [uv](https://docs.astral.sh/uv/) (it also fetches Python 3.12+ if you do not have it)
+- `git`
+- [Claude Code](https://claude.com/claude-code), to run the guided phases
+- [`gh`](https://cli.github.com/), logged in with the `repo` and `project` scopes
+  (`gh auth login`, then `gh auth refresh -s project`), to create things on GitHub
+
+`project-kit doctor` checks all of this for you. Spec Kit is installed for you at the end, if
+you want it.
+
+## Install
+
+```bash
+uv tool install project-kit-cli      # installs the `project-kit` command
+uv tool upgrade project-kit-cli      # later, to update the program
+```
+
+The package is called `project-kit-cli`; the command is `project-kit`. To try it without
+installing: `uvx --from project-kit-cli project-kit help`.
+
+**Updating a project.** `init` copies the skills and templates into your repository and never
+overwrites them, so a new version of the program does not change a project that already exists.
+Run `project-kit upgrade` inside it to see what is out of date, and `project-kit upgrade --apply`
+to bring it up to date. Files you edited are never overwritten; see
+[upgrading](https://github.com/miguelmatg/project-kit/blob/main/docs/upgrade.md).
+
+## Quick start
+
+In your repository, new or existing:
+
+```bash
+cd my-project
+project-kit init
+```
+
+`init` copies the skills and templates into the repository and then offers to open Claude Code
+right there, already running `/pk-start` (press Enter to accept). `/pk-start` asks whether to
+**only initialise** or to **start defining the project now**, and after every phase it asks
+whether to continue or stop. You can leave at any point and come back later:
+
+```bash
+project-kit status     # where you are and what comes next
+project-kit help       # a visual guide to the flow and the commands
+```
+
+## The phases
+
+| # | Skill | What it does | Produces |
+|---|---|---|---|
+| 0 | `/pk-start` | Checks your setup and lets you choose: only initialise, or start now | `.project-kit/` |
+| 1 | `/pk-discover` | Interviews you about the project: problem, users, scope, constraints | `docs/project/brief.md` |
+| 2 | `/pk-decide` | Guides the technical decisions: monolith or monorepo, language, package manager, data, auth, hosting | `docs/adr/*.md` |
+| 3 | `/pk-workflow` | Agrees how the team works: branches, reviews, quality gates | `docs/development-workflow.md` |
+| 4 | `/pk-plan` | Derives phases, epics and a backlog from all of the above | `docs/project/roadmap.md`, `.project-kit/backlog.json` |
+| 5 | `/pk-provision` | Creates milestones, labels, branches, the GitHub Project and the issues | GitHub |
+| 6 | `/pk-handoff` | Prepares the Spec Kit constitution; each issue becomes a spec | `.project-kit/handoff/constitution-input.md` |
+
+Each phase ends with an explicit approval (`project-kit approve <phase>`), and a phase cannot be
+approved while an earlier one is still open. The phases are listed in `.project-kit/workflow.yml`;
+for a small project, switch one off with `enabled: false`.
+
+To fill a document by hand instead, copy the matching template from `.project-kit/templates/`
+(`brief.md`, `adr.md`, `development-workflow.md`). The skills read what is already there and only
+ask about what is missing.
+
+## Existing repositories and Projects
+
+`init` never overwrites a file, so it is safe in a repository that already has code, documents or
+a `.claude/` folder. Before creating a GitHub Project, `provision` looks at the ones already
+linked to the repository: with one it asks whether to use it, with several it lists them, and
+with none it asks for a name. Use `--project <number or title>` to choose without being asked.
+It never rewrites issues that already exist, and re-running it is always safe.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `project-kit init` | Install the skills, templates and workflow in the current directory |
+| `project-kit status` | Show the phases and what comes next |
+| `project-kit upgrade [--apply] [--adopt] [--diff]` | Update the skills and templates a project already has |
+| `project-kit help` | Show a visual guide (also what plain `project-kit` prints) |
+| `project-kit doctor` | Check that git, gh, uv and Spec Kit are available |
+| `project-kit approve <phase>` | Record your sign-off of a phase |
+| `project-kit backlog validate` | Validate `.project-kit/backlog.json` |
+| `project-kit provision [--dry-run] [--project X]` | Create milestones, branches, the Project and issues on GitHub |
+| `project-kit handoff [--install-speckit]` | Generate the Spec Kit constitution input |
+
+Useful `init` options: `--project-name`, `--language` (language of the generated documents),
+`--agent claude|none` (open the agent or not) and `--ai-coauthor keep|remove`.
+
+## AI co-author
+
+`init` asks whether AI assistants may appear as co-authors of your commits and pull requests. If
+not, it configures Claude Code to stop signing them and installs a `commit-msg` hook that strips
+the co-author trailer of other assistants. Switch the hook on once per clone with
+`git config core.hooksPath .githooks`.
+
+## After the handoff
+
+`/pk-handoff` leaves a text file for Spec Kit's constitution and tells you the next step:
+
+```
+/speckit-constitution @.project-kit/handoff/constitution-input.md
+```
+
+From there Spec Kit does the work. Each issue of the backlog is one spec: its text is the input of
+`/speckit-specify`, followed by `/speckit-clarify`, `/speckit-plan`, `/speckit-tasks` and
+`/speckit-implement`. project-kit never writes inside `.specify/` and does not write specs.
+
+The constitution is generated from your own rules: the branch pattern and merge strategy you agreed,
+the decisions on record, and an index of where each kind of rule lives (including the GitHub
+Project used for tasks). Once the constitution is written, `project-kit approve handoff` deletes
+the temporary input files; from then on the constitution is the single source.
+
+## What it adds to your repository
+
+```
+.project-kit/          config.yml, state.json, workflow.yml, templates/, handoff/
+.claude/skills/pk-*/   the skills
+docs/project/          brief.md, roadmap.md        (created by the phases)
+docs/adr/              one file per decision       (created by the phases)
+.githooks/commit-msg   only if you removed the AI co-author
+```
+
+## Documentation
+
+More detail lives in the repository (in Spanish):
+[design](https://github.com/miguelmatg/project-kit/blob/main/docs/design.md),
+[backlog schema](https://github.com/miguelmatg/project-kit/blob/main/docs/backlog-schema.md),
+[provisioning](https://github.com/miguelmatg/project-kit/blob/main/docs/provisioning.md) and
+[Spec Kit handoff](https://github.com/miguelmatg/project-kit/blob/main/docs/handoff.md).
+
+## Feedback
+
+Ideas and bug reports are welcome as
+[issues](https://github.com/miguelmatg/project-kit/issues). Pull requests are not accepted; see
+[CONTRIBUTING](https://github.com/miguelmatg/project-kit/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/miguelmatg/project-kit/blob/main/LICENSE)

{project_kit_cli-0.1.0 → project_kit_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"

{project_kit_cli-0.1.0 → project_kit_cli-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "project-kit-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Project definition and dev-workflow kit that hands off to Spec Kit"
 readme = "README.md"
 requires-python = ">=3.12"

{project_kit_cli-0.1.0 → project_kit_cli-0.2.0}/src/project_kit/ai_attribution.py

@@ -60,6 +60,11 @@ def install_hook(root: Path) -> tuple[Path | None, str]:
     return HOOK, ""
 
 
+def hook_bytes() -> bytes:
+    """The shipped commit-msg hook, as it is installed."""
+    return (files("project_kit") / "assets" / "hooks" / "commit-msg").read_bytes()
+
+
 def hook_is_active(root: Path) -> bool:
     """True if git is already pointed at ``.githooks`` in this repository."""
     config = root / ".git" / "config"

{project_kit_cli-0.1.0 → project_kit_cli-0.2.0}/src/project_kit/approval.py

@@ -4,6 +4,7 @@ from pathlib import Path
 
 from project_kit.backlog import load_backlog
 from project_kit.config import load_config
+from project_kit.handoff import CONSTITUTION, INPUT_FILE, constitution_ready
 from project_kit.state import PHASES, State, StateError, load_state, save_state
 from project_kit.workflow import load_workflow
 
@@ -29,6 +30,12 @@ def approve_phase(root: Path, phase: str) -> State:
         )
     if phase == "plan":
         load_backlog(root)
+    if phase == "handoff" and not constitution_ready(root):
+        raise StateError(
+            f"The Spec Kit constitution is not written yet ({CONSTITUTION.as_posix()} is missing "
+            "or still the template). In Claude Code run "
+            f"/speckit-constitution @{INPUT_FILE.as_posix()} first."
+        )
     state.approve(phase)
     if PHASES.index(phase) > PHASES.index(state.phase):
         state.phase = phase

project_kit_cli-0.2.0/src/project_kit/assets/skills/pk-handoff/SKILL.md

@@ -0,0 +1,57 @@
+---
+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, with a selection list (`AskUserQuestion`: **No extra rules** / **Yes, I have some**),
+   whether the project has rules of its own that should be part of the constitution
+   (security, compliance, performance, team conventions). If yes, collect them and write them
+   as a Markdown list to `.project-kit/handoff/constitution-extra.md`; they are added under
+   "Project-specific rules". Governance content only: no feature requests, no implementation
+   tasks. Everything else the constitution needs (principles, the branch pattern and merge
+   strategy from `config.yml`, the decisions on record, and an index of where each kind of rule
+   lives, including the GitHub Project used for tasks) is generated for you.
+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 choice to go ahead,
+   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. When the constitution is written, read `.specify/memory/constitution.md` and check that it
+   kept what the input said: the branch pattern and the merge strategy of `config.yml`, the
+   section "Where the project's rules live" (or its content) and the reference to the GitHub
+   Project for tasks. If something is missing, tell the user and suggest amending it with
+   `/speckit-constitution` before continuing.
+7. 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.
+8. When the user confirms the constitution is in place, run `project-kit approve handoff`. It
+   refuses while `.specify/memory/constitution.md` is missing or still Spec Kit's template, and
+   when it succeeds it **deletes** `constitution-input.md` and `constitution-extra.md`: they
+   only exist to feed `/speckit-constitution`, and from then on the constitution is the one
+   source. Tell the user they were removed.
+
+## Rules
+
+- `constitution-input.md` is regenerated every time until the handoff is approved. 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.
+- Both files are temporary. After the handoff, rules change by amending the constitution with
+  `/speckit-constitution`, not by recreating them.
+- 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_cli-0.1.0 → project_kit_cli-0.2.0}/src/project_kit/assets/skills/pk-provision/SKILL.md

@@ -16,17 +16,23 @@ This writes to the provider, so nothing happens without the user's explicit cons
 
 ## 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.
+1. Run `project-kit provision --dry-run`. You have no terminal for the command's own
+   questions, so it never asks: it uses the only Project it finds, or stops and tells you what
+   to choose. 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.
+     repository (`already exists`) or a new one. Ask which one they want with a selection
+     list (`AskUserQuestion`, see `.project-kit/templates/interview.md`): the detected
+     Project (Recommended), another existing one, or a new one (then ask its name). Whatever
+     they choose, run the dry run again with `--project "<number or exact title>"` (a new
+     title creates it), so the plan matches. The choice is remembered afterwards.
+   - If it stops with "Several Projects match this repository" or "There is no terminal to
+     ask which GitHub Project to use", offer the listed Projects (up to three, plus "Other"
+     for a new name) in a selection list and rerun with `--project`.
+2. Ask with a selection list whether to go ahead (**Create it all** / **Not yet**). Only after
+   the first run `project-kit provision --yes` (with the same `--project`). 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.
 

{project_kit_cli-0.1.0 → project_kit_cli-0.2.0}/src/project_kit/assets/skills/pk-start/SKILL.md

@@ -16,24 +16,26 @@ now. Nothing is created in GitHub or GitLab here.
    - `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
+   provider, language, branches) and ask with a selection list (`AskUserQuestion`: **It is
+   right** / **Change something**) 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:
+   asked yet, ask with a selection list (**Keep them as co-authors** / **Remove them**) 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:
+4. **Ask how far to go now**, with a selection list (`AskUserQuestion`, see
+   `.project-kit/templates/interview.md`) and exactly these two options. Put B first with
+   `(Recommended)` unless the user said they are in a hurry:
 
    | 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.
+   | **A. Only initialise** | Stop here. The user comes back later with `/pk-discover` |
 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

{project_kit_cli-0.1.0 → project_kit_cli-0.2.0}/src/project_kit/assets/skills/pk-workflow/SKILL.md

@@ -36,11 +36,28 @@ Read `.project-kit/templates/interview.md` first and follow it.
 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.
+3. **Record what was agreed as data** in `.project-kit/config.yml`: the handoff generates the
+   Spec Kit constitution from these values, not from the prose of the document, so they must
+   say the same thing as the document:
+
+   ```yaml
+   branches:            # the three permanent branches (three different names)
+     main: main
+     release: release
+     develop: develop
+   workflow:
+     spec_branch: "spec/<name>"   # how the branch of one spec is named
+     merge:                       # how pull requests are merged into each branch
+       develop: squash            # squash | merge | rebase
+       release: merge
+       main: merge
+   ```
+
+   If the user changes branch names or drops `release`/`develop`, edit `branches:` too. Tell
+   the user what you wrote.
 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`.
+5. **Approval gate.** On an explicit choice of "Approve it", 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
@@ -48,4 +65,6 @@ Read `.project-kit/templates/interview.md` first and follow it.
 - 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.
+- The document and the `workflow:` / `branches:` values of `config.yml` must never disagree.
+  If the user changes one later, change the other.
 - Write in the language of `config.yml`.

{project_kit_cli-0.1.0 → project_kit_cli-0.2.0}/src/project_kit/assets/templates/constitution-input.md

@@ -9,7 +9,7 @@ nothing in this document asks for features to be built.
 
 ### I. Spec-driven development (NON-NEGOTIABLE)
 Every feature follows specify, clarify, plan, tasks, implement. There is no product code
-without an approved spec. Each spec lives in its own branch `NNN-name`, created from
+without an approved spec. Each spec lives in its own branch `{{spec_branch}}`, created from
 `{{branches.develop}}`, and in `specs/NNN-name/`. Trivial changes (typos, dependency bumps,
 configuration) may go as `chore/*` without a spec.
 
@@ -47,13 +47,12 @@ in `docs/adr/`.
 
 - Permanent branches: `{{branches.main}}` (released product), `{{branches.release}}`
   (testing and acceptance) and `{{branches.develop}}` (development).
-- Working branches start from `{{branches.develop}}`: `NNN-name` (one per spec), `chore/*`,
+- Working branches start from `{{branches.develop}}`: `{{spec_branch}}` (one per spec), `chore/*`,
   `docs/*` and `fix/*`. `hotfix/*` starts from `{{branches.main}}`.
 - Promotion flows `{{branches.develop}}` to `{{branches.release}}` to `{{branches.main}}`. A
   hotfix goes to `{{branches.main}}` and `{{branches.release}}` and is then propagated back
   to `{{branches.develop}}`.
-- Squash merge into `{{branches.develop}}`; merge commit into `{{branches.release}}` and
-  `{{branches.main}}`. Releases are tagged `vX.Y.Z` (SemVer) on `{{branches.main}}`.
+- {{merge_summary}} Releases are tagged `vX.Y.Z` (SemVer) on `{{branches.main}}`.
 - Commits follow Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `test:`,
   `refactor:`, `ci:`).
 - Everything goes through a pull request. There is no direct push to a permanent branch.
@@ -70,6 +69,13 @@ in `docs/adr/`.
 ## Decisions on record
 
 {{decisions}}
+
+## Where the project's rules live
+
+Follow these sources instead of restating them in a spec. When two disagree, fix the source
+that is wrong rather than working around it.
+
+{{rules_index}}
 {{extra}}
 ## Governance