---
name: project-foundation
description: Lay the foundation of a software project before implementation — intake, vision, requirements (PRD), research, blueprint with C4 views, architecture decision records, roadmap and issues, repository rules (AGENTS.md), owner approval — by running the UASK Engineering Hub playbook mgmt.project-foundation with its templates. Use when the owner asks to start a project properly, write a vision, PRD or blueprint, re-found or rewrite an existing product, or begin large new work on a product that has no foundation documents.
license: CC-BY-4.0
compatibility: Any coding agent that reads Markdown and uses git. The GitHub CLI (gh) is used for issues and milestones when available.
metadata:
  hub-playbook: mgmt.project-foundation
  hub-playbook-version: 0.4.3
---

# Project foundation

This skill runs the playbook `mgmt.project-foundation`. The playbook holds the rules, the stages and their
entry and exit criteria; this skill only says how an agent carries them out. Where the two seem to differ,
follow the playbook and report the difference.

## Before you start

1. Find the Hub. In a project that vendors it, read `.uask/hub/`; otherwise read the UASK Engineering Hub
   repository the owner points to. Note the release or commit you read; it goes into the foundation issue
   and into the project's `AGENTS.md` (`mgmt.project-foundation#R11`).
2. Read the playbook (`content/playbooks/project-foundation.md`) in full, then `arch.adr`
   (`content/core/architecture/adr.md`) and `arch.c4-model` (`content/core/architecture/c4-model.md`).
3. You are the lead developer. You draft, research, propose and verify; the owner approves, accepts and
   decides scope (`mgmt.project-foundation#R9`). Read the project's existing `AGENTS.md`, if there is one,
   for anything stricter.
4. If your environment does not list this skill by name — a vendored copy under `.uask/hub/skills/` is not
   always registered — open its `SKILL.md` and follow it as written; say so in the run record or the issue.

## Steps

Run the stages in order (`mgmt.project-foundation#R2`). Close a stage only when its exit criteria in the
playbook are met (`mgmt.project-foundation#R3`). Each artefact starts as a copy of its template, keeps the
template's front matter and the sections not marked "Optional", and goes to the path below or to the
path recorded at intake (`mgmt.project-foundation#R4`).

| Stage | Copy | To |
|---|---|---|
| 2 Vision | `templates/vision.md` | `project/VISION.md` |
| 3 Requirements | `templates/prd.md` | `project/PRD.md` |
| 5 Blueprint | `templates/blueprint.md` | `project/BLUEPRINT.md` |
| 6 Decisions | `templates/adr.md` | `project/decisions/NNNN-<slug>.md` |
| 7 Roadmap | `templates/roadmap.md` | `project/ROADMAP.md` |
| 8 Bootstrap | `templates/agents.md` | `AGENTS.md` |
| 1 Intake, without a tracker | `templates/run-record.md` | `project/RUN.md` |
| 1 Intake, from a client's request | `templates/client-brief.md` | `intake/CB-NNN.md`, in a private folder |

1. **Intake.** Open the foundation issue: the owner's brief verbatim, what is already known, the roles, the
   tailoring and the questions (`mgmt.project-foundation#R1`). Create branch `docs/<issue>-foundation`. Ask
   the owner all blocking questions in one message, then wait for the tailoring to be confirmed — this is
   the only stop before the gate. Propose the governance tier (`mgmt.governance-tiers`) with your reasons; the
   owner decides it. With no tracker or repository, keep the brief and the tailoring in the run record instead of
   an issue, and list stage 8 as skipped with the reason.
   When the work starts as a client's request, first run the step "From a request to an estimate and G0" of the playbook
   (`mgmt.project-foundation#R19`, `mgmt.project-foundation#R20`); do not write to the client.
2. **Vision.** Fill `project/VISION.md` from the brief and the answers. Ask the owner to confirm the
   statement and the non-goals in the issue; continue with requirements meanwhile.
3. **Requirements.** Fill `project/PRD.md`. Give every scenario, requirement and acceptance criterion an
   id (`mgmt.project-foundation#R5`) and name the vision outcome each scenario serves; check that no outcome is
   left unserved. Add the operability targets (`mgmt.project-foundation#R13`). If the work replaces or rebuilds a
   running system, walk the checklist "External interfaces and environment" of the PRD template with the people
   who know the system and the hosting, and turn each entry into a requirement, a criterion or a dropped item
   (`mgmt.project-foundation#R12`). For each acceptance criterion write the method, the environment, the
   expected result and who performs it, then ask whether it can really be performed in that environment
   (`mgmt.project-foundation#R14`). For a product that already exists, show what works in one parity table
   instead of many requirements.
4. **Research.** Write one note per blocking question in `research/`. Run independent questions in
   parallel (subagents or separate sessions) and keep their output in files. Compare at least two options
   with sources and access dates, measurements or spikes (`mgmt.project-foundation#R8`); a spike is named in
   its note and is not merged as product code (`mgmt.project-foundation#R10`). Where earlier reports exist,
   write `research/index.md` that links them and says which blocking question each answers, instead of copying.
5. **Blueprint.** Fill `project/BLUEPRINT.md`: context and container views as `arch.c4-model` describes
   (`mgmt.project-foundation#R7`), stack, risks, implementation sequence; for a replacement of a running
   system also the cutover and rollback sequence. Mark each significant choice **[ADR-NNNN]**, or
   `[ADR-candidate Dn]` while it has no number (`mgmt.project-foundation#R6`). Ask a reviewer who did not write it — the technical lead
   or a second agent given only the files — to look for gaps and risks.
6. **Decisions.** Write one ADR per mark, status `proposed`, following `arch.adr`, and replace every
   `[ADR-candidate Dn]` mark with the link. For an existing product, also record the decisions already in force:
   status stays `proposed`, the owner decision section names the date and the source of the earlier decision,
   and `date:` is the day you write the record (`mgmt.project-foundation#R9`).
7. **Roadmap and issues.** Fill `project/ROADMAP.md`; create the milestones and one issue per deliverable,
   each citing the requirement ids it serves (with `gh issue create` and `gh api` for milestones when the
   tracker is GitHub). Without a tracker, give each deliverable an id in the roadmap and write a brief file.
8. **Repository bootstrap.** Fill `AGENTS.md`; add `CLAUDE.md` with the single line `@AGENTS.md` plus
   Claude-only notes; make CI run one check script; add a pull request template. On a live system take
   and verify a backup first (`ops.backups`).
9. **Owner approval gate.** Open the foundation pull request (closing the foundation issue) with: the
   artefacts, one list of decisions needed from the owner, assumptions and main risks. Leave statuses at
   `review` and `proposed`. When the owner asks for a change, go back to that stage and carry the change
   forward to every later artefact. Without a pull request, ask the owner to set `status: approved` with the
   date in each artefact.

## Before you report a stage as closed

- Every exit criterion of the stage in the playbook is met; say how you checked each one.
- Run `python3 .uask/hub/tools/check_artifacts.py .` (in the Hub repository, `tools/check_artifacts.py`) and
  fix every `FAIL` line: template front matter and sections, unique and resolving ids, ADR files. A `WARN` line
  is yours to judge. Add `--require vision,prd,blueprint` to make a missing artefact an error.
- What the tool cannot see you check yourself, with a small script or by hand: each requirement is covered by
  the blueprint and the roadmap, each acceptance criterion can be performed where it says, each number agrees
  with its source.
- A project that writes in its own language keeps the template's section headings in English, because the
  tool matches them.
- Technical claims carry a source, a measurement or a check, or are marked as assumptions.

## Report

After each stage, at most five lines: the stage, the artefact paths, exit criteria met or not, questions
for the owner. Details belong in the artefacts and the pull request, not in chat.
