Project foundation (skill)
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.
Download SKILL.md — the skill, as in the repository.
When to use
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.
- Carries out the playbook Project foundation (written for version 0.4.3).
- Source:
skills/project-foundation/SKILL.md· licence CC-BY-4.0. - Works with: Any coding agent that reads Markdown and uses git. The GitHub CLI (gh) is used for issues and milestones when available.
- To install skills: Get started with the Hub in your project.
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
- 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’sAGENTS.md(mgmt.project-foundation#R11). - Read the playbook (
content/playbooks/project-foundation.md) in full, thenarch.adr(content/core/architecture/adr.md) andarch.c4-model(content/core/architecture/c4-model.md). - 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 existingAGENTS.md, if there is one, for anything stricter. - If your environment does not list this skill by name — a vendored copy under
.uask/hub/skills/is not always registered — open itsSKILL.mdand 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 |
- 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 branchdocs/<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. - Vision. Fill
project/VISION.mdfrom the brief and the answers. Ask the owner to confirm the statement and the non-goals in the issue; continue with requirements meanwhile. - 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. - 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, writeresearch/index.mdthat links them and says which blocking question each answers, instead of copying. - Blueprint. Fill
project/BLUEPRINT.md: context and container views asarch.c4-modeldescribes (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. - Decisions. Write one ADR per mark, status
proposed, followingarch.adr, and replace every[ADR-candidate Dn]mark with the link. For an existing product, also record the decisions already in force: status staysproposed, the owner decision section names the date and the source of the earlier decision, anddate:is the day you write the record (mgmt.project-foundation#R9). - Roadmap and issues. Fill
project/ROADMAP.md; create the milestones and one issue per deliverable, each citing the requirement ids it serves (withgh issue createandgh apifor milestones when the tracker is GitHub). Without a tracker, give each deliverable an id in the roadmap and write a brief file. - Repository bootstrap. Fill
AGENTS.md; addCLAUDE.mdwith the single line@AGENTS.mdplus 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). - 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
reviewandproposed. 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 setstatus: approvedwith 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 everyFAILline: template front matter and sections, unique and resolving ids, ADR files. AWARNline is yours to judge. Add--require vision,prd,blueprintto 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.