011-black-jack/.claude/skills/project-planning/SKILL.md

name, description

name	description
project-planning	Plan a project (or a new phase of one) in phases with tasks, and sync those phases and tasks to Gitea or GitHub as Milestones and Issues. Use when starting a new project, adding or updating a phase/gateway, breaking a phase down into tasks, deciding whether a task needs its own use case or user story, or asked to create/update project milestones or issues on the git host.

Project Planning

Plans a project as phases (gateways), each phase as a set of tasks, and keeps those phases and tasks in sync with the git host's own project management (Milestones and Issues). It builds on the artifact skill's PP (Project Plan) and MIL (Milestone/Gateway) types.

Domain language first

Before planning, find the Product Owner's (PO's) domain language. Take it from the first of these that states it:

1. the user's prompt;
2. a file the user included or that the project already has (the Languages section of docs/artifact-registry.md).

If none states it, ask the user for it and stop planning until it is answered; never assume one. Record the answer in the registry's Languages section. If it differs from the project's working language, the high-level artifacts are also kept in it (see the registry's translation list).

Start here

Before planning or building anything, check that the baseline exists (the docs/artifact-registry.md rows and files): the Business Case (BC), the Stakeholder Analysis (SA), the Project Plan (PP) and at least one milestone (MIL). If one is missing, create it first, in that order, with new-artifact.sh (it refuses when a type in the catalog's Requires column is missing).

A "build X" request is planning-first. Produce the phases, tasks and issues, show the dry run of sync-project.sh, and ask for a go-ahead before any code is written; running --apply is the user's decision. Only the user can waive the plan, in chat, for that request; the waiver does not carry over. The rule is defined in framework/process/plan-first-gate.md.

The hierarchy

Business goal → Feature/requirement → Use case/user story → Tasks

The use case/user story explains why a feature exists; tasks explain how the team implements it. Not every task needs a use case:

• Needs a use case/user story — the task is something a user, or another system, actually does: "User resets password", "Admin exports customer report", "Payment service processes refund".
• Plain task, no use case — purely technical/implementation work: "Refactor authentication middleware", "Add database index", "Upgrade React version", "Fix null-pointer bug", "Add unit tests", "Configure CI pipeline", "Optimize SQL query".

When in doubt, ask: does this row describe a goal an actor is pursuing, or a step the team takes to build something? Goals get a use case; steps stay a plain task.

Use cases get their own folder

Each use case lives in docs/uc-NNN/ (UC-001 → docs/uc-001/), together with the artifacts that belong to it. Nothing about a use case goes in a shared docs/use-cases/ folder.

1. Create the folder and the use case: bash framework/scripts/new-artifact.sh UC --file docs/uc-001/uc.md.

2. Create only the artifacts this use case affects, in this order, each in the same folder with a fixed file name. Skip any it does not touch (no erd.md if nothing is stored; no dm.md if it adds no concept).

   Order	Type	File	Create when the use case…
   1	SSD	ssd.md	has system interaction to show (almost always)
   2	DM	dm.md	introduces or changes domain concepts
   3	OC	oc.md	has system operations that change state
   4	SD	sd.md	needs a collaboration design for an operation
   5	DCD	dcd.md	adds or changes design classes
   6	ERD	erd.md	adds or changes persisted data

   bash framework/scripts/new-artifact.sh SSD --file docs/uc-001/ssd.md
   bash framework/scripts/new-artifact.sh DM  --file docs/uc-001/dm.md      --cite UC-001=docs/uc-001/uc.md
   

   new-artifact.sh cites only the artifacts in the same use-case folder (and project-level ones); for DM, DCD and ERD, add the use case and sibling artifacts by hand with --cite. Each gets its own ID (the next version in the registry, e.g. DM-002) and its own RC-* review.

3. Reconcile with the project models. The use-case artifacts are a scoped view; the project-level docs/domain-model.md, docs/dcd.md and docs/erd.md are the consolidated truth. When the use case's DM, DCD or ERD are done, compare each with its project-level document:

   • add the new concepts, classes, attributes and entities; change the ones the use case modified;
   • keep names identical to the existing ones, and resolve any conflict with another use case's model instead of duplicating the element;
   • give each project-level document a new ## Version History row (Change: which use case caused it), and create it from the first use case's document if it does not exist yet;
   • if nothing needs to change, say so in the use case's task and PR description ("project DM/DCD/ERD unchanged: ").

Planning a project (or a new phase)

1. Phases are gateways. Each phase is a MIL-* document (the artifact skill's MIL type): purpose, deliverable, Go/No-Go criteria, dependencies, ownership, target date. Create one with bash framework/scripts/new-artifact.sh MIL --file docs/milestones/mil-<NNN>-<slug>.md.
2. The plan schedules the phases. docs/project-plan.md (the artifact skill's PP type) lists every phase with its window and owner, and holds the overall timeline diagram. Create it once with bash framework/scripts/new-artifact.sh PP.
3. Break each phase into tasks. In the phase's ## Tasks section, add one row per task using the hierarchy rule above. Tasks that need a use case or user story get one created first (UC/US types; a use case follows "Use cases get their own folder" below), then are referenced from the Tasks row; plain tasks just describe the work.
4. Sync to the git host. Run the sync tool (below) to create or update the corresponding Milestones and Issues. Do this whenever a phase or its tasks change — the tool is idempotent (matches by title, never creates a duplicate).

Syncing to Gitea/GitHub

bash framework/scripts/sync-project.sh              # prints the plan only — no network calls
bash framework/scripts/sync-project.sh --milestone MIL-002   # limit to one phase
bash framework/scripts/sync-project.sh --apply      # actually create/update on the git host

• Default is a dry run: it parses docs/milestones/mil-*.md and prints what would be created or updated. Nothing is sent anywhere.
• --apply performs the real requests. It needs:
  • Gitea (default — detected from origin's hostname): GITEA_TOKEN env var, a personal access token. This is an HTTP API call (milestones, issues) — a deploy key cannot be used, since deploy keys only authenticate SSH git transport (clone/fetch/push), not the REST API. Scope the token to issues only if your Gitea version supports scoped tokens, rather than a full-account one.
  • GitHub (detected when origin is on github.com, or pass --host github): the gh CLI, already logged in (gh auth login).
• --with-project additionally tries to create/attach a Kanban Project board. This is best-effort: some Gitea versions (confirmed on 1.27.3) show Projects/Kanban only in the web UI and expose no REST API for it at all, so this always fails there — check your server's own https://<host>/swagger.v1.json for any project path if unsure. GitHub Projects (v2) needs gh with the project scope. Either way the script warns and continues; Milestones and Issues are unaffected. Where there's no API, create the board by hand at https://<host>/<owner>/<repo>/projects.
• Read the script's header comment for the full flag list, including --owner, --repo, --api-base to override auto-detection.

--apply is an outward-facing, hard-to-reverse action (it creates real Milestones/Issues on the git host) — run it yourself once you're ready, or ask explicitly for it to be run.

Branching before commits

Never commit, push or open a PR unless the user asks. The user reviews the working-tree changes first; finish the edits, summarise them and stop. Everything below (branching, closing keywords, resolving commit links, the PR) describes how to do those steps once the user has asked for them; it is not permission to start them.

Never commit directly on main. This is enforced locally by a pre-commit hook (framework/githooks/pre-commit) once bash framework/scripts/install-git-hooks.sh has been run in this clone — run it once per clone; it points core.hooksPath at the versioned framework/githooks/ instead of the per-clone, untracked .git/hooks/. The hook refuses the commit with a pointer back to this section; a rare, deliberate exception can bypass it with ALLOW_MAIN_COMMIT=1 git commit.

Before the first commit of a piece of work, create and switch to a new branch, then commit there:

git checkout -b <branch-name>
# ... commits ...
git push -u origin <branch-name>

• Name the branch for the gateway/task it covers, kebab-case, e.g. g2-kpi-bmc-bpmn or mil-002-kpi-baseline — short enough to read in a PR list, specific enough to say what it's for.
• Open a PR (gh pr create on GitHub, or the Gitea equivalent) instead of merging straight to main; this project's own history is a merged PR per phase (e.g. "Merge pull request 'Close G1 inception baseline...'"), so keep following that pattern.
• This applies to every commit, not just gateway/task work — if in doubt whether the current branch is main, check (git branch --show-current) before committing.

Closing tasks from commits

When a commit finishes the work for a task that sync-project.sh has already synced as an Issue, reference that Issue number in the commit message so Gitea/GitHub auto-closes it once that commit lands on the default branch (main) — via the PR merge required by "Branching before commits" above, not by pushing the closing keyword to a feature branch. Use Refs #N instead when the commit only touches the task without finishing it — that links the commit without closing.

• One issue per commit: use Closes #5.

• Several issues closed by the same commit: put one Closes #N per line, not a comma-separated list (Closes #5, #6, #7 only closed #5 on a confirmed live Gitea instance — the comma form is not reliably parsed):

  Closes #5
  Closes #6
  Closes #7
  

• Get each issue number either from the most recent sync-project.sh / sync-project.sh --apply output (it prints updated issue #N / created issue #N per task) or, if that's not at hand, from the git host's issue list for the milestone.

• Match commits to issues by the task row they implement — one task row in a MIL-* document's ## Tasks section is one Issue, so a commit that completes that row's work closes that Issue.

• Don't guess an issue number; if it isn't known from a recent sync or a lookup, ask rather than omit or fabricate one.

• After pushing a multi-issue closing commit, verify each issue's state came back closed (e.g. GET /repos/<owner>/<repo>/issues/<N> with GITEA_TOKEN) rather than assuming the whole list closed; close any that didn't with a direct PATCH .../issues/<N> {"state":"closed"} call.

Pull requests close the issues they complete

Every PR must close the Issues its work finishes, so the board matches reality once it merges. Before opening (or updating) a PR:

1. List the issues the branch completes. Go through the task rows the branch implements (git log main..HEAD, plus the ## Tasks of the MIL-* it belongs to) and get each Issue number as described in "Closing tasks from commits".

2. Put one closing line per issue in the PR description, one per line, never comma-separated:

   Closes #5
   Closes #6
   

   Use Refs #N for an issue the PR only touches. A PR that finishes no issue says so explicitly ("No issue closed: ") instead of saying nothing.

3. Ask, don't guess. If an issue number is unknown or a task is only partly done, ask rather than omit or invent one. Leave a partly done task open and note what remains.

4. After the merge, verify that each issue is closed (the check in "Closing tasks from commits") and close any stragglers by hand. Also make sure the finished task rows are reflected in the MIL-* document and, when every task of a phase is closed, that the Milestone is closed too.

5. Resolve pending commit links before the PR (see "Version History rule" in the artifact skill): commit, run bash framework/scripts/resolve-pending-commits.sh <changed docs>, then commit the result as a follow-up commit.

6. Never ask for, offer or perform the merge. A PR needs a reviewer: ask the user to open the PR / request a review, and stop there. Merging, enabling auto-merge and "shall I merge?" are not yours to do.

Closing keywords in the PR description and in commit messages both count on Gitea and GitHub; they only take effect when the PR merges into the default branch.

Files this skill touches

• docs/project-plan.md — PP, via the artifact skill.
• docs/milestones/mil-*.md — MIL, via the artifact skill, each with a ## Tasks section.
• docs/uc-NNN/*.md (the use case and its SSD, DM, OC, SD, DCD, ERD), docs/user-stories.md — only for tasks that need one; plus docs/domain-model.md, docs/dcd.md, docs/erd.md when reconciling.
• framework/scripts/sync-project.sh — never edited per project; propose changes upstream in the framework.