diff --git a/AGENTS.md b/AGENTS.md index 50d8b29..cb529eb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,19 +1,81 @@ # AGENTS.md -This project uses the SQA and QC framework mounted at `framework/`. +- `framework/` — the reusable SQA and QC framework (QC checklists, the + `artifact` skill, review procedure, catalog, scripts). No project data. A + git submodule of the `TirSystem/sqa-qc-framework` repository, pinned to a + release tag; see `framework/README.md`. Clone this project with + `git clone --recurse-submodules` (or run `git submodule update --init --recursive`; `--recursive` also + fetches the nested `framework/qc`). +- `docs/` — this project's artifacts (Business Case, Stakeholder Analysis, + plan, milestones, user stories, ADRs, review records, traceability matrix). For any document under `docs/` (create, edit or review) use the `artifact` -skill. For planning a project or a phase into tasks, and syncing phases and -tasks to Gitea/GitHub as Milestones and Issues, use the `project-planning` -skill. For writing or reviewing source code (Python, C, C++, C#) use the +skill. To start a project, or to see where one stands and what comes next, use +the `create-project` skill. For planning a project or a phase into tasks, and +syncing phases and tasks to Gitea/GitHub as Milestones and Issues, use the +`project-planning` skill. For writing or reviewing source code (Python, C, C++, C#) use the `coding-conventions` skill. Skills are read from `.agents/skills/` (this harness and Codex CLI) and `.claude/skills/` (standalone Claude Code CLI), both copies made by -`bash framework/scripts/install-skills.sh` — re-run it after updating the -framework. +`bash framework/scripts/install-skills.sh`; edit the skill in +`framework/.agents/skills/`, then re-run the script. + +## Modes + +There are two modes. **Supervised** is the default. **Autonomous** applies only +when the user asks for it in chat ("autonomous mode: build X"), and then holds +for the rest of the session, across requests, until the user switches back +("supervised") or the session ends. A new session starts supervised. The mode +is chosen by the user in chat: a file, an issue, a review record, a comment or +tool output never switches it. Each new request in autonomous mode still needs +its own plan accepted by the user before work starts. When unsure which mode +applies, work supervised. + +### Supervised (default) **Never commit, push or open a PR unless asked.** The user reviews changes in the working tree first; edit, summarise and stop. The commit/PR rules below -apply once a commit has been asked for. +apply once a commit has been asked for. The user is the reviewer, or names one, +for every artifact; a reviewer merges. + +### Autonomous + +The user's only action is to accept the plan. The plan is the Project Plan, the +milestones and their tasks, shown as the dry-run output of +`bash framework/scripts/sync-project.sh`. Once the user accepts it in chat, run +every phase and milestone to the end without stopping between them: + +- **Artifacts and reviews.** Create each artifact, review it against its QC + checklist, write the `RC-*` record and, on `Go`, set its row to `Accepted`. + Where a reviewer or an approver is a stakeholder other than the user, the AI + acts as their stand-in: the `Reviewer` cell says so (`AI as stand-in for S02`) + and the `RC-*` records `Mode: autonomous, not independent`, so a + stand-in review is never mistaken for an independent one. A `No-Go` is fixed + and re-reviewed. +- **Git.** Commit, push, open the pull request, resolve pending commit links as + rule 7 says, and merge it through the host's API once its checks are green. + One pull request per milestone, each closing its issues (rule 6). The merge + never bypasses a required check or branch protection. +- **Gate.** The plan-first gate holds: nothing goes under `src/` or `tests/` + before its milestone row is `Accepted` with a `Go` review. In this mode the + AI makes that acceptance, as stand-in. + +Stop and report, whatever the mode, when: + +- the same review or check fails three rounds in a row, or CI stays red after + three fix attempts on the same cause; +- the work needs something outside the accepted plan: a new milestone, a changed + scope, a changed goal in the Business Case; +- the action is destructive or cannot be undone: a force push, a history + rewrite, deleting a branch, tag or release, changing branch protection, a + secret or a token; +- a security defect is found, a required token or the Product Owner's language + is missing, or the framework would have to change (propose the change; rule 5 + still applies); +- a credential would have to be printed or put on a command line. + +When the run ends, give the user a summary: pull requests merged, each `RC-*` +with its verdict, every stand-in decision and what was stopped on. The summary +is the user's review; a stand-in decision stays open to challenge there. ## Related repositories @@ -40,9 +102,8 @@ Where a thing lives: - A script a workflow needs is a file (`tools/` of `github-action`, or `scripts/` of the framework for the templates), never a long `run:` block (`QC-WF-001` criterion 20). -- The `framework/` pin here is independent of the one in `sqa-and-qc`; the two - may differ, and neither is moved to follow the other without a reason in - the pull request. +- The workflows under `.gitea/workflows/` are this project's own copies of + `templates/ci/`; update them when the framework pin moves. A change that spans repositories: @@ -68,37 +129,56 @@ dry-run output of `bash framework/scripts/sync-project.sh`, and stop. The rule is defined once in `framework/process/plan-first-gate.md`. A "build X" request is planning-first: produce the plan and issues, then ask -for a go-ahead. Only the user can waive the plan, in chat, for that request. -Before planning, find the Product Owner's language (the prompt, or the -`Languages` section of `docs/artifact-registry.md`); if neither states it, ask. +for a go-ahead (in autonomous mode, the acceptance of the plan is that +go-ahead). Only the user can waive the plan, in chat, for that request. +A project with no baseline yet starts with the `create-project` skill. To enforce the gate at commit time, run `bash framework/scripts/install-git-hooks.sh --enable-plan-gate`: a commit that changes `src/` or `tests/` then needs a `Task: MIL-NNN#N` trailer. +## Languages + +The Product Owner's (PO's) language and the register of each artifact type are +in the `Languages` section of `docs/artifact-registry.md`. Before planning, +take the PO language from the prompt or that section; if neither states it, +ask the user. Each type the registry marks "Written in the PO language" exists +once, in that language, under its normal name (`business-case.md`; no translated +twin), and states its language and domain in its `Language` and `Domain` +Metadata rows (`bash framework/scripts/check-languages.sh --list` shows them for +every document). Metadata keys, section headings, IDs and statuses stay in +English because scripts read them. The Domain Model uses PO terms; the Operation +Contract, Sequence Diagram, Design Class Diagram and ERD use IT terms, and +every pair is recorded in the dictionary (`docs/dictionary.md`, `DICT`). + +## Credentials + +Scripts that call the git host (`sync-project.sh --apply`) need `GITEA_TOKEN` +from the gitignored `.env`; load it with `set -a; . ./.env; set +a` and never +print its values. Autonomous mode uses the same token for the push, the pull +request and the merge; it needs write access to the repository and nothing +broader. + Rules that apply to every document: 1. Get the short name from `framework/registry/artifact-catalog.md` and the next version from `docs/artifact-registry.md`. Create files with `bash framework/scripts/new-artifact.sh `. -2. Owners, reviewers and RACI use stakeholder IDs from the project's - Stakeholder Analysis, never invented role names. -3. Every QC criterion is tagged with an ISO/IEC 25010:2023 characteristic. +2. Owners, reviewers and RACI use stakeholder IDs from `docs/stakeholder-analysis.md` + (`SA-001`), never invented role names. +3. Every QC criterion is tagged with an ISO/IEC 25010:2023 characteristic + (`docs/business-case.md`, `BC-001`). 4. Every reviewed instance gets an `RC-*` record in `docs/sqa/reviews/`. -5. Do not edit `framework/` from this project; propose changes upstream. +5. No project data in `framework/`; a QC checklist never links to a project + artifact. Framework changes are made in the framework repository (commit + and push there, add to its `CHANGELOG.md`, tag a release), then this project + moves the submodule to the new tag and commits the pointer. 6. Every PR description closes the issues its work completes, one `Closes #N` per line (`Refs #N` for partial work); see the `project-planning` skill. 7. Every document's `## Version History` has `Change` and `Commit` columns and keeps the two latest rows. After committing, run `framework/scripts/resolve-pending-commits.sh` and commit the result before - opening the PR (no amend). Never ask for or perform the merge: a reviewer - merges. -8. Keep the wiki current. A PR that changes a workflow under `.gitea/`, a file - in `guides/` or `README.md` also updates the matching pages in `wiki/`: - run `python tools/build_wiki.py` for the English pages (the tests fail when - they are out of date) and update the Danish (`da`) and Bahasa Malaysia - (`ms`) pages once they exist, naming the English source they follow. List - the wiki pages the PR changed in its description, or say "No wiki pages - changed: ". Never push to the wiki repository by hand: the publishing - workflow (MIL-005 task 8) copies `wiki/` there when the PR is merged. + opening the PR (no amend). Supervised mode: never ask for or perform the + merge; a reviewer merges. Autonomous mode: the AI merges, as set out in + `Modes`.