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

project_kit/assets/templates/adr.md

@@ -0,0 +1,32 @@
+# ADR-NNNN: <decision title>
+
+<!-- One decision per file, named docs/adr/NNNN-short-title.md. Written by /pk-decide, or fill
+     it in by hand. Status: Proposed, Accepted, Deprecated or Superseded by ADR-NNNN. -->
+
+- **Status**: Proposed
+- **Date**: YYYY-MM-DD
+
+## Context
+
+<!-- The problem or constraint that forces a decision, with links to the brief. -->
+
+## Decision drivers
+
+<!-- What matters for choosing: team skills, cost, time, scale, compliance, lock-in... -->
+
+-
+
+## Options considered
+
+| Option | Pros | Cons |
+|--------|------|------|
+| A | | |
+| B | | |
+
+## Decision
+
+<!-- The option chosen, in one sentence, and the main reason. -->
+
+## Consequences
+
+<!-- What gets easier, what gets harder, what must be done as a result, when to revisit. -->

project_kit/assets/templates/backlog.example.json

@@ -0,0 +1,59 @@
+{
+  "version": 1,
+  "phases": [
+    {"id": "mvp", "title": "v0.1 MVP", "description": "First usable version"},
+    {"id": "growth", "title": "v0.2", "description": "Improvements after the first feedback"}
+  ],
+  "labels": [
+    {"name": "area:backend", "color": "0E8A16", "description": "Server side"},
+    {"name": "area:frontend", "color": "1D76DB", "description": "User interface"}
+  ],
+  "issues": [
+    {
+      "id": "epic-accounts",
+      "type": "epic",
+      "phase": "mvp",
+      "title": "User accounts",
+      "priority": "P1",
+      "size": "L",
+      "body": "Users can sign up, sign in and manage their profile."
+    },
+    {
+      "id": "adr-auth",
+      "type": "adr",
+      "phase": "mvp",
+      "title": "Decide the authentication approach",
+      "priority": "P1",
+      "size": "S",
+      "parent": "epic-accounts",
+      "body": "Compare hosted identity providers with in-house authentication."
+    },
+    {
+      "id": "sign-up",
+      "type": "feature",
+      "phase": "mvp",
+      "title": "Sign up with email and password",
+      "priority": "P1",
+      "size": "M",
+      "parent": "epic-accounts",
+      "labels": ["area:backend", "area:frontend"],
+      "body": "A visitor can create an account.",
+      "acceptance": [
+        "The form validates the email and the password strength",
+        "A confirmation email is sent",
+        "Duplicate emails are rejected with a clear message"
+      ]
+    },
+    {
+      "id": "profile-page",
+      "type": "feature",
+      "phase": "growth",
+      "title": "Profile page",
+      "priority": "P3",
+      "size": "S",
+      "parent": "epic-accounts",
+      "labels": ["area:frontend"],
+      "acceptance": ["A signed-in user can see and edit their display name"]
+    }
+  ]
+}

project_kit/assets/templates/brief.md

@@ -0,0 +1,77 @@
+# Project brief: {{project_name}}
+
+<!-- Written by /pk-discover, or fill it in by hand. Describe WHAT and WHY, not HOW:
+     technology and architecture are decided in the next phase. -->
+
+- **Status**: Draft
+- **Created**: YYYY-MM-DD
+
+## Summary
+
+<!-- Two or three sentences: what it is, for whom, and why it is worth building. -->
+
+## Problem
+
+<!-- Who hurts, what hurts, and what happens today without this project. -->
+
+## Users and stakeholders
+
+<!-- Users experience the problem; stakeholders decide, pay or are affected. -->
+
+- **Users**:
+- **Stakeholders**:
+
+## Goals
+
+-
+
+## Scope
+
+<!-- The capabilities the project must offer, at product level and grouped by theme. -->
+
+### In scope
+
+-
+
+### Out of scope (non-goals)
+
+-
+
+## Success criteria
+
+<!-- How will you know it worked? Measurable and independent of technology where possible. -->
+
+-
+
+## Constraints
+
+<!-- Legal and compliance, budget, deadline, team size and skills, existing systems, hosting
+     or data-residency requirements. -->
+
+-
+
+## Data and integrations
+
+<!-- What information the project handles and which external services it must talk to. -->
+
+-
+
+## Technical preferences already stated
+
+<!-- Anything the user already decided or wants to avoid (languages, tools, hosting). It is
+     not decided here: /pk-decide takes it as input and turns it into ADRs. -->
+
+-
+
+## Risks and assumptions
+
+-
+
+## Open questions
+
+<!-- [NEEDS CLARIFICATION: ...] -->
+
+## Clarifications
+
+<!-- ### Session YYYY-MM-DD
+     - Q: ... -> A: ... -->

project_kit/assets/templates/constitution-input.md

@@ -0,0 +1,78 @@
+<!-- project-kit:managed -->
+# {{project_name}} constitution input
+
+Governance principles for {{project_name}}, generated by project-kit from the project's
+decisions. They are meant to be passed to `/speckit-constitution`. Governance content only:
+nothing in this document asks for features to be built.
+
+## Core principles
+
+### 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
+`{{branches.develop}}`, and in `specs/NNN-name/`. Trivial changes (typos, dependency bumps,
+configuration) may go as `chore/*` without a spec.
+
+### II. Test-first and verifiable quality
+Domain logic is written test-first (red, green, refactor). Integration tests cover the
+boundaries between components, and contract tests cover every API or schema change. Nothing
+is merged without a green CI. A fixed bug includes the test that reproduces it.
+
+### III. Security and secrets
+Authorisation is enforced on the server side. Secrets live only in a secrets manager or in
+the hosting platform's secrets, never in the repository (a `.env.example` without values is
+versioned instead). Personal data is handled according to the applicable regulation and that
+handling is documented in the spec that touches it.
+
+### IV. Automation and reproducibility
+Infrastructure and processes are versioned configuration. There are no manual changes that
+are not reflected in the repository, and critical tasks are idempotent and retryable.
+
+### V. Simplicity
+Choose the simplest solution that validates the product. Any extra complexity is justified in
+writing, in the plan's complexity tracking or in an ADR.
+
+### VI. Decisions in writing
+Every cross-cutting decision (stack, authentication, data, deployment) is recorded as an ADR
+in `docs/adr/`.
+
+## Additional constraints
+
+- Technology stack: {{stack}}
+- Language: documents and specs are written in `{{language}}`; code, commits and branch
+  names are in lowercase English.
+{{references}}
+
+## Development workflow and quality gates
+
+- 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/*`,
+  `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}}`.
+- 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.
+- Branch protection is not configured by project-kit. Where the hosting plan does not offer
+  it (for example a private repository on a free GitHub plan) these rules are followed by
+  discipline; where it is available it should be enabled.
+- The project board is the source of truth for planning. A card becomes Ready only when it
+  has acceptance criteria. Work in progress is limited to one spec In progress and one In
+  review.
+- Definition of Done: acceptance criteria met, tests green in CI, documentation and ADRs
+  updated, the pull request references its issue (`Closes #N`) and the working branch is
+  deleted.
+
+## Decisions on record
+
+{{decisions}}
+{{extra}}
+## Governance
+
+This constitution prevails over other practices. Amendments are proposed by pull request
+against `{{branches.develop}}` with a justification and are versioned with SemVer. Every plan
+includes a check against this constitution, and any deviation is justified in writing.

project_kit/assets/templates/development-workflow.md

@@ -0,0 +1,51 @@
+# Development workflow: {{project_name}}
+
+<!-- Written by /pk-workflow, or fill it in by hand. It records how the team works; the
+     handoff phase turns it into the Spec Kit constitution. -->
+
+- **Status**: Draft
+
+## Team and ways of working
+
+<!-- Who works on the project, how many people, and how they review each other's work. -->
+
+## Branches
+
+<!-- Permanent branches and the types of working branch, where each one starts and where it
+     goes. Default: main / release / develop, with one branch per spec. -->
+
+| Branch | Purpose | Starts from | Merges into |
+|--------|---------|-------------|-------------|
+| `main` | Released product | | |
+| `release` | Testing and acceptance | | |
+| `develop` | Integration | | |
+
+## Pull requests and reviews
+
+<!-- Who approves, how many approvals, merge strategy per branch. -->
+
+## Commits and versions
+
+<!-- Commit convention, versioning scheme, tags and releases. -->
+
+## Repository and tooling
+
+<!-- Single repository or monorepo; package manager and workspace tool; formatters, linters
+     and hooks. These follow from the ADRs: link them instead of repeating them. -->
+
+## Quality gates
+
+<!-- What must be green before merging: tests, lint, type checks, security scans, coverage. -->
+
+## Definition of Done
+
+-
+
+## Open questions
+
+<!-- [NEEDS CLARIFICATION: ...] -->
+
+## Clarifications
+
+<!-- ### Session YYYY-MM-DD
+     - Q: ... -> A: ... -->

project_kit/assets/templates/github/ISSUE_TEMPLATE/adr.yml

@@ -0,0 +1,21 @@
+name: Decision (ADR)
+description: Pending architecture or process decision
+labels: ["type:adr"]
+body:
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+    validations:
+      required: true
+  - type: textarea
+    id: options
+    attributes:
+      label: Options
+      description: Alternatives with pros and cons
+    validations:
+      required: true
+  - type: textarea
+    id: recommendation
+    attributes:
+      label: Recommendation

project_kit/assets/templates/github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,25 @@
+name: Bug
+description: Something does not work as it should
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected and observed behaviour
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, tool versions

project_kit/assets/templates/github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

project_kit/assets/templates/github/ISSUE_TEMPLATE/epic.yml

@@ -0,0 +1,15 @@
+name: Epic
+description: Groups several issues of the same delivery
+labels: ["type:epic"]
+body:
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal
+    validations:
+      required: true
+  - type: textarea
+    id: children
+    attributes:
+      label: Child issues
+      placeholder: "- [ ] #123"

project_kit/assets/templates/github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,22 @@
+name: Feature
+description: New functionality or improvement
+labels: ["type:feature"]
+body:
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What problem it solves and why
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      placeholder: "- [ ] ..."
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes

project_kit/assets/templates/github/pull_request_template.md

@@ -0,0 +1,21 @@
+## What changes
+
+<!-- Short summary of the change and why -->
+
+## Related issue
+
+Closes #
+
+## Type
+
+- [ ] Feature
+- [ ] Fix
+- [ ] Documentation
+- [ ] Decision (ADR)
+- [ ] Chore
+
+## Checklist
+
+- [ ] The PR targets the right branch (`{{branches.develop}}`; `{{branches.release}}` and `{{branches.main}}` only by promotion)
+- [ ] Affected documentation is updated
+- [ ] Tests pass (if applicable)

project_kit/assets/templates/interview.md

@@ -0,0 +1,68 @@
+<!-- Shared by pk-discover, pk-decide and pk-workflow. Same technique as Spec Kit's clarify. -->
+# How project-kit interviews
+
+Every guided phase follows these rules. Edit this file to change the style of the questions
+for the whole project.
+
+## Before asking anything
+
+1. Read `.project-kit/config.yml`: write everything in its `language`.
+2. Read the document the phase produces if it already exists. The user may have filled it in
+   by hand or in an earlier session. Only ask about what is **Missing** or **Partial**; never
+   ask again what the document already answers.
+3. Read the documents of the earlier phases: they are the context, not something to ask again.
+4. Build, internally, a list of the topics of the phase marked Clear / Partial / Missing. Do
+   not show it unless there is nothing left to ask.
+5. Keep the questions that change what gets built or decided, ordered by impact times
+   uncertainty. Drop trivia and anything that belongs to a later phase.
+
+## Asking
+
+- **One question at a time.** Never reveal the questions that are still queued.
+- Start the line with `**Question:**` and make it a full question that ends in `?` and makes
+  sense on its own (no topic labels as questions). Follow it with one plain sentence,
+  `Why it matters:`, saying what depends on the answer.
+- When there are discrete options (2 to 5, mutually exclusive), say which one you recommend
+  and why, then list all of them:
+
+  `**Recommended:** Option B - <one or two sentences of reasoning for this project>`
+
+  | Option | Description |
+  |--------|-------------|
+  | A | ... |
+  | B | ... |
+  | Other | Your own answer |
+
+  Close with: `Reply with a letter, say "yes" to take the recommendation, or write your own
+  answer.`
+- When there are no discrete options, offer a suggested answer instead:
+  `**Suggested:** <answer> - <reason>`, and accept "yes" or "suggested" as agreement.
+- If an answer is ambiguous, ask a quick follow-up. It does not count as a new question.
+- Stop when the topics that matter are Clear, when the user says "done", "enough" or "skip",
+  or when you reach the question limit of the phase. Unanswered topics stay in the document
+  as `[NEEDS CLARIFICATION: <question>]`.
+
+## Recording
+
+- **Save the document after each accepted answer**, not at the end, so nothing is lost if the
+  session stops.
+- Put each answer in the section where it belongs, replacing the text it makes obsolete
+  instead of adding contradictions. Keep each statement short and verifiable.
+- Log it too, under `## Clarifications` > `### Session YYYY-MM-DD`, as
+  `- Q: <question> -> A: <answer>`.
+- Where the user left a choice open, make an informed guess from the context, write it down
+  under **Assumptions** and say so. Use `[NEEDS CLARIFICATION: ...]` only when the choice
+  changes the scope or has no reasonable default, with a maximum of three at the end of a
+  pass.
+- Never invent facts about the user's business, users or constraints.
+
+## Finishing
+
+1. Tell the user what was written and which markers remain open.
+2. Offer a clarification pass: "Do you want me to look for gaps and ask a few more
+   questions, or is this good enough to approve?" A pass asks at most 5 more questions.
+3. Approval gate: ask explicitly whether the document is approved. Only an explicit "yes" in
+   this conversation allows running `project-kit approve <phase>`. Never approve on the
+   user's behalf, and never because an earlier question was answered.
+4. After approving, run `project-kit status` and offer the next phase: continue now, or
+   stop here and come back later with its skill. Respect the answer.