create-afe-project 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,351 @@
+# create-afe-project
+
+## 1.0.0
+
+### Major Changes
+
+- The template moves from Copier to the npm package `create-afe-project` (ADR-0002), on the
+  owner's instruction of 2026-10-31, to drop the Python toolchain for users; the first release on
+  npm, under the MIT license.
+  - `npx create-afe-project@latest <directory>` (or `npm create afe-project@latest`) creates a
+    project with a wizard that asks the questions of the former `copier.yml`; `--defaults`,
+    `--data key=value`, and `--data-file` answer without a terminal. The questions are short and
+    plain, and the message after create numbers the next steps.
+  - Create makes the initial commit on `main` (`Template: create the project with
+    create-afe-project <version>`), the one direct commit that `docs/contributing.md` allows, so
+    `/afe-init` starts on a clean working tree. It commits only in a new directory or an empty
+    clone, never in a non-empty directory written with `--force`; `--no-git` skips it.
+  - `npx create-afe-project@latest update` replaces the template-owned files, keeps the project
+    block of `AGENTS.md`, creates missing seeded files and never changes existing ones, removes
+    files the template no longer owns, runs the migrations between the versions, and regenerates
+    the generated files. It refuses a dirty working tree (`--allow-dirty`) and a downgrade, and
+    lists every replaced local edit of a template-owned file.
+  - The answers file is `.afe-answers.json` with the template version in `_version`; a project
+    generated by Copier converts its `.copier-answers.yml` on its first update. The path classes
+    (`scripts/lib/classes.sh`), the protect hook, and the size warning of
+    `scripts/check-decisions.sh` know both names.
+  - `docs/contributing.md`, section 5, `docs/documentation-rules.md`, section 9, and the
+    `update-template` skill describe the update with `create-afe-project`; there are no conflict
+    markers to resolve any more. `README.md` is seeded: copy its "Project template" and "Checks"
+    sections by hand.
+- A generated project needs only Git, bash, and Node.js: jq and lychee are gone.
+  - The hooks, `scripts/gen-settings.sh`, and `scripts/pr-metrics.sh` read and write JSON with the
+    new `scripts/lib/json.mjs`; the protect hook now blocks when Node.js is missing.
+  - `scripts/check-links.mjs` replaces lychee: offline, every relative link and image of the
+    Markdown files points at an existing file, and every anchor at a heading or an HTML id of its
+    target. `scripts/check-docs.sh` and the `docs` workflow run it; `lychee.toml` is removed.
+- The `docs` workflow also runs on `workflow_dispatch`, so a workflow can start it for a pull
+  request opened with `GITHUB_TOKEN`.
+- A second pass over the AFE guide, on the owner's decisions of 2026-10-31; no observed failure.
+  - `afe-init` skill (new, run by the owner only): interviews the owner about the product, the
+    stack, and the stage; records requirements, an accepted stack ADR, and a proposed
+    architecture; scaffolds the code with the stack's own generator; wires format, lint, types,
+    unit and end-to-end tests into `scripts/checks.d/` and `.claude/harness.conf`; and proves
+    that every gate fails when it should. Three pull requests, one change each.
+  - The check after every edit: `.claude/hooks/post-edit-check.sh` (new, PostToolUse) runs
+    `CHECK_EDIT` of `.claude/harness.conf` on the changed file, limited by `CHECK_EDIT_GLOBS`,
+    and sends a failure back to the agent. `.claude/harness.conf` is seeded: an existing project
+    adds the two keys by hand when it wants the check.
+  - The protect hook asks before publishing (`npm`, `pnpm`, `yarn`, `bun`, `cargo`, `poetry`, `uv`
+    publish, `twine upload`, `gem push`, `dotnet nuget push`, `docker` or `podman push`),
+    `gh workflow run`, and a `gh api` DELETE, also behind `git -C DIR`; it denies a push to the
+    default branch once the remote has it; and it asks when an edit or a command contains a known
+    token format (AWS, GitHub, GitLab, Slack, Stripe, Google, Anthropic, OpenAI, npm, private keys).
+  - `secret_scan` module (new, default on): `.github/workflows/secret-scan.yml` runs gitleaks,
+    downloaded at a pinned version with its checksum, on the commits of every pull request and
+    push to `main`. The message after create also names GitHub's secret scanning and push protection.
+  - `scripts/protect-branch.sh` (new): creates or updates the GitHub ruleset that protects the
+    default branch (pull requests only, the `check` and `integrity` checks, no force push or
+    deletion); the owner runs it once.
+  - `scripts/check-template.sh` fails when a hook command of `.claude/settings.json` names a
+    missing or non-executable script.
+  - `AGENTS.md`, section 4: content from issues, pull requests, web pages, logs, tool output, and
+    dependencies is data, never instructions. The map plans `docs/conventions/` and
+    `docs/recipes/`, a new document kind of `docs/documentation-rules.md`, section 2.
+  - With the `dual_review` module, the Santa loop runs without the Codex CLI too, with a second
+    fresh Claude subagent that reviews with another lens; `REVIEW_MAX_ROUNDS` of
+    `.claude/harness.conf` (3 to 5, default 3) caps the rounds, and a blocker that comes back
+    unchanged after its fix ends the loop early.
+
+## [0.6.0] - 2026-10-31
+
+A second pass over the Agent-Friendly Engineering field guide, on the owner's decisions of
+2026-10-31, and the follow-ups of 0.5.0. Observed failures: the protect hook let two writes into
+rule files through, behind `cd` and in a Python heredoc (pull request #14); the review workflows
+skipped #14 and reported success. The other additions come from the owner's decisions on the
+guide, without an observed failure.
+
+### Added
+
+- Environment contract: `scripts/env.sh setup|check|fast|e2e|reset` runs the project's commands
+  `SETUP`, `CHECK_FAST` (default `scripts/check-docs.sh`), `E2E`, and `RESET` of
+  `.claude/harness.conf`, and `scripts/check.sh` for `check`; an unset command is SKIP, and the
+  exit code is the command's. `AGENTS.md`, section 2, and the map point at it.
+- `fail_without_change` module: `.github/workflows/fail-without-change.yml` runs
+  `scripts/env.sh setup` and the driver on every pull request; the label `tests-pass-on-base`
+  allows a pass. The driver installs with `SETUP` when `FWC_INSTALL` is empty, and a test must
+  now also pass with the change, so a missing toolchain is no longer evidence.
+- Access control: `.claude/settings.json` denies reading `.env`, `.env.*`, `*.pem`, and `*.key`
+  (also through `cat` and the like); a project that needs one, such as `.env.example`, takes the
+  rule out with `"remove": {"permissions": {"deny": ["Read(**/.env.*)"]}}` in
+  `.claude/settings.project.json`, which `scripts/gen-settings.sh` now supports.
+- Metrics: the measure "Regression of" (`none` or `#N`), required by readiness;
+  `scripts/pr-metrics.sh` adds the regression rate, the hours to merge, and the median and
+  maximum of each measure.
+- A small diff: readiness warns, without failing, above `DIFF_WARN_LINES` (default 400) changed
+  lines, generated files left out.
+- `contracts/*` is class high by default in `.claude/path-classes`.
+
+### Changed
+
+- Review before the pull request runs without the `dual_review` module too: one pass by a fresh
+  Claude subagent, which `create-pr` runs, for classes normal, gate, and high; the module adds
+  the Codex CLI and the Santa loop. `review-code` always checks that "Checks" names it.
+- `.claude/hooks/protect-docs.sh`: a target behind `cd DIR` or `git -C DIR` resolves against
+  that directory; the file names in an interpreter's heredoc are targets; the body of another
+  heredoc is not read as commands.
+- `docs/contributing.md`: section 1, a session that stops unfinished leaves a checkpoint
+  (commits pushed, progress and blockers in the plan or the description), and GitHub deletes
+  merged branches; section 5, shorter; section 6, a defect fix gives the evidence pack.
+- `docs/documentation-rules.md`, section 2: acceptance criteria as Given, When, Then with their
+  checks; architecture holds the system map with domain ownership and dependency rules.
+  `docs/testing-rules.md`: the project names the levels of its verification ladder.
+
+### Seeded files: what an existing project does by hand
+
+- `.claude/harness.conf`: add `SETUP=`, `CHECK_FAST=scripts/check-docs.sh` (or the project's
+  fast check), `E2E=`, `RESET=`, and `DIFF_WARN_LINES=400`.
+- `.claude/path-classes`: add `high contracts/*` when the project has contracts.
+- `docs/README.md`: the row "Environment commands" names `scripts/env.sh`; the planned rows of
+  architecture and operations name the system map, domain ownership, and dependency rules, and
+  logs, traces, metrics, and scenario replay.
+- On GitHub, turn on "Automatically delete head branches" in the repository settings.
+
+## [0.5.0] - 2026-10-31
+
+The process follows the Agent-Friendly Engineering principles: the owner sets outcomes and
+risks, agents report evidence, checks enforce, and governance follows risk and reversibility.
+Recurring failure addressed: in `xandronak/brain`, pull requests #14, #15, and #18 each needed
+three or more AI review rounds that never converged, because every round found new edge cases;
+and each owner decision needed a separate confirmation. Additions without an observed failure,
+from the owner's decisions on the AFE field guide (2026-10-30): the invariants register, the
+environment commands, access control for irreversible actions, and the size budget. Open pull
+requests of an existing project need the new description sections before readiness passes.
+
+### Added
+
+- Path classes (`docs/documentation-rules.md`, section 8): low, normal, gate, high, approval, by
+  built-in rules and the new seeded `.claude/path-classes` (`<class> <glob>` lines), with
+  defaults for several ecosystems. Each class decides approval before the edit (approval: the
+  protect hook asks), the listing in the pull request (gate: "Gate files"), and the review
+  before it (none, one reviewer, or the Santa loop for high). `scripts/lib/classes.sh` and
+  `scripts/check-decisions.sh --classes` print the class of each changed path and the review it
+  needs. `AGENTS.md`, section 4, follows the classes.
+- Loops (`docs/contributing.md`, sections 3 and 6): the Ralph loop on `scripts/check.sh` for
+  every change, capped by `RALPH_MAX_ITERATIONS` (default 5) in the new seeded
+  `.claude/harness.conf`; the Santa loop for class high only, with a Claude subagent and the
+  Codex CLI until neither finds a blocker, and after the third round the open blockers go to the
+  owner. Other classes get one pass; only the fix of a blocker is checked again.
+- Definition of done in `docs/contributing.md`, section 3, which `AGENTS.md`, section 6, points
+  at; it replaces the definition-of-done line of `docs/documentation-rules.md`, section 6.
+- Modules `acceptance_check` (`scripts/check-acceptance.sh`: every identifier of the Acceptance
+  section appears in a test file of `TEST_GLOBS`; run by readiness) and `fail_without_change`
+  (`scripts/fail-without-change.sh`: each new or changed test fails on the base, in a temporary
+  worktree, with the project's own `FWC_INSTALL` and `FWC_TEST`, an optional `FWC_CLASSIFIER`,
+  and `--allow-pass-on-base` for the label `tests-pass-on-base`). Both off by default.
+- `scripts/check-decisions.sh --ready` also fails on: no "Acceptance and test plan"; an
+  Acceptance item that is neither "None" with a reason nor names an existing path in backticks;
+  an added `Decided by the owner, YYYY-MM-DD` marker in a Markdown file that "Owner decisions"
+  does not name; a touched gate file that "Gate files" does not name; Metrics tables outside
+  their forms, answers that do not add up, a blocker recorded as a limit, or a missing measure.
+- `scripts/pr-metrics.sh`: sums the Metrics tables of merged pull requests with `gh`, names the
+  sensors without a finding, and warns when `--limit` cuts the period. `docs/maintaining.md`,
+  section 6 (this repository): at each release a rule or check that never fired is proposed for
+  removal, and a new one names the recurring failure it addresses.
+- Access control: `.claude/settings.json` is now generated by `scripts/gen-settings.sh` from the
+  template-owned `.claude/settings.template.json` and the new seeded
+  `.claude/settings.project.json`, where the project adds its own permission rules; the template
+  denies force pushes and remote branch deletions in the forms its rules spell out.
+  `scripts/check-template.sh` fails on a stale `.claude/settings.json`.
+- `.claude/hooks/protect-docs.sh`: asks for class approval paths (`approval` lines of
+  `.claude/path-classes`, `.claude/settings.project.json`, `.mcp.json`, the generated settings),
+  and for the irreversible commands it names: `git push` that forces, deletes, mirrors, prunes,
+  or pushes tags (`--tags`, `refs/tags/...`, `v<digit>...`), `gh pr merge`, `gh release create`
+  and `delete`, `gh repo delete`.
+- Line budgets checked by `scripts/check-template.sh`: `AGENTS.md` 90 template lines,
+  `docs/documentation-rules.md` 200, `docs/contributing.md` 200, `docs/testing-rules.md` 80. The
+  four rule documents together are shorter than in 0.4.1.
+- The invariants register `docs/invariants.md` as a planned document kind; its invariants are
+  criteria of the Santa loop. Environment commands in the map, pointed at from `AGENTS.md`. One
+  git worktree per parallel session (`docs/contributing.md`, section 1).
+
+### Changed
+
+- `docs/contributing.md`, section 3: description sections Summary, Acceptance and test plan,
+  Checks, Assumptions and open questions, Owner decisions, Gate files, Metrics (two fixed
+  tables), Notes for the owner. The new label `limit:` records a suggestion the branch does not
+  fix. A failing check keeps its command and output. The owner's merge confirms the listed
+  markers; readiness waits for no confirming comment and no second round.
+- `docs/contributing.md`, section 6: AI review is a sensor; classes `blocker` and `suggestion`;
+  each finding is answered once; a suggestion never drives a loop. The `docs-review` and
+  `code-review` workflows run once, when a pull request opens or leaves draft; a push or a reopen
+  does not run them again.
+- `docs/testing-rules.md`: the agent derives the test plan from the identifiers, as a report; a
+  refactoring keeps the tests; a behaviour change changes the requirement first, then the test
+  with the same identifier; gate configurations are class gate; the threat model of development
+  gates only decides which bypass is a blocker.
+- Skills: `dual-review` reviews by class; `create-pr` runs the Ralph loop, writes the new
+  sections, waits for the review runs once, and has a fixed blocker checked once by a fresh
+  subagent; `review-code` and `docs-review` use the two classes and no longer judge whether a
+  marker matches the owner's words.
+
+### Removed
+
+- The `should`/`nit` classes and their example table, the brief rule for later rounds, the
+  escalation after three rounds outside the Santa loop, "Owner decisions to confirm" and its
+  confirming comment, the template-update exemption of 0.4.1 (now class low), and the checklist
+  of `docs/contributing.md`, section 4, which is now one paragraph.
+- `.claude/protected-paths` is no longer seeded; the hook and the class checks still read its
+  glob lines as class approval.
+
+### Seeded files: what an existing project does by hand
+
+- An update creates `.claude/path-classes`, `.claude/harness.conf`, and
+  `.claude/settings.project.json` with the defaults, and deletes `.claude/protected-paths`; a
+  `_migrations` entry of `copier.yml` appends its glob lines to `.claude/path-classes` as
+  `approval <glob>`. Check them by hand: gate configuration, such as test runner and linter
+  files, becomes `gate <glob>`. Add the project's own high paths
+  (brain: policy, limits, accounting). Set `TEST_GLOBS`, `FWC_TEST`, and `FWC_INSTALL` in
+  `.claude/harness.conf` before turning on the new modules (`copier update --data
+  acceptance_check=true --data fail_without_change=true`).
+- `.claude/settings.json` becomes generated: a project that edited it moves its own rules into
+  `.claude/settings.project.json` and runs `scripts/gen-settings.sh`.
+- `docs/README.md`: add the row "Environment commands: set up, check, fast check, end-to-end
+  tests, reset" (check: `scripts/check.sh`; the others the project's commands or "not
+  decided"), the planned row "Invariants" (`docs/invariants.md`), and in the rows of the agent
+  rules, the documentation rules, and checks and enforcement the new terms: autonomy by risk,
+  when a change is done, path classes and access, `.claude/path-classes`,
+  `.claude/harness.conf`, `.claude/settings.project.json`, `scripts/pr-metrics.sh`.
+
+## [0.4.1] - 2026-10-30
+
+### Changed
+
+- `docs/contributing.md`, sections 3, 4, and 6 (with `dual_review`): a template update that
+  changes only template-owned and generated files is exempt from the dual review; its
+  description says "Dual review: not run: template update to X.Y.Z". The `create-pr`,
+  `dual-review`, and `review-code` skills apply the exemption: `review-code` takes that line in
+  place of a verdict.
+
+## [0.4.0] - 2026-10-30
+
+### Changed
+
+- `docs/testing-rules.md`, section 4: a threat model of development gates. Gates catch honest
+  mistakes and shortcuts; deliberate evasion is left to the review of the diff; product
+  invariants are not development gates. The protected-paths bullet now names the forms the
+  protect hook catches and what is left to the review, instead of claiming that no agent loosens
+  a gate.
+- `docs/documentation-rules.md`, section 7: the merge-readiness row names what
+  `scripts/check-decisions.sh --ready` checks and what is left to the owner.
+- `docs/contributing.md`, section 6: a finding that only deliberate evasion can exploit to bypass
+  a development gate is a `nit`, a bypass of a product invariant keeps its severity, and a table
+  of `should` and `nit` examples calibrates every reviewer. The Tests criterion includes the test
+  plan. With `dual_review`, later rounds add the owner's decisions on the branch to the brief, and
+  nothing else.
+- `docs/contributing.md`, section 1: "one logical change" means one mechanism with its tests and
+  owner documents, with examples.
+- `docs/contributing.md`, section 3: the description gains the sections "Test plan" (always,
+  written before the implementation) and "Owner decisions to confirm" (each `Decided by the
+  owner` marker added on a chat instruction, confirmed by the owner with one comment); a pull
+  request is ready to merge only after that confirmation. `scripts/check-decisions.sh --ready`
+  does not check the confirmation.
+- `docs/documentation-rules.md`, sections 3 and 7: a statement about a check names the forms it
+  catches and what is left to the review; an absolute claim needs a test for each form it covers.
+- `create-pr` skill: writes the two new sections and reports unconfirmed owner decisions as
+  waiting on the owner. `review-code` skill: compares the code and tests with the test plan.
+  `dual-review` skill: an author's self-check before the first round, the severity examples and
+  the test plan in the brief, and the owner's decisions from the second round.
+
+### Fixed
+
+- `.claude/hooks/protect-docs.sh`: judges a target path by the git repository that holds it when
+  that repository has `.template/owned.txt`, so an edit in a sibling git worktree, or in another
+  generated project, asks the owner like an edit in the session's own checkout. Other paths
+  inside the session's project are judged by the project as before (no git yet, a nested
+  repository); paths elsewhere stay unguarded. A relative path of a shell command resolves
+  against the hook input's `cwd`.
+- `.claude/hooks/protect-docs.sh`: folds `.` and `..` in the part of a target path that does not
+  exist yet before the match, so a write to `newdir/../AGENTS.md` or `docs/new/../README.md` asks
+  the owner, and a path whose `..` leaves the repository no longer matches a protected glob.
+
+## [0.3.1] - 2026-10-30
+
+### Changed
+
+- `docs/contributing.md`, section 6: defines the severities `blocker`, `should`, and `nit`, and
+  that a review fails on a `blocker` or `should` only; a reviewer who hesitates picks `nit`. The
+  `review-code`, `docs-review`, and `dual-review` skills apply these definitions, and a `nit` no
+  longer fails a round of the dual review.
+- `review-code` and `docs-review` skills: in a pull request run they read changed files of
+  `.claude/`, `CLAUDE.md`, and `.mcp.json` from the diff and `.claude-pr/`, because
+  `anthropics/claude-code-action` restores those paths from the base branch.
+
+## [0.3.0] - 2026-10-30
+
+### Added
+
+- Testing rules (`docs/testing-rules.md`), template-owned: what a test is for, how it proves
+  behaviour, tests and the change they cover, and the gates no agent loosens. `AGENTS.md`,
+  section 2, points to it; `docs/documentation-rules.md`, sections 2, 6, and 7, list it.
+- Review of pull requests (`docs/contributing.md`, section 6): a rubric that every reviewer
+  applies, the project's own criteria in an owner document that the map names under "Review
+  criteria", and the rule that a defect found after the merge names what keeps the next one out.
+- Module `code_review` (question `code_review`, default on): the `code-review` workflow
+  (`.github/workflows/code-review.yml`) and the `review-code` skill
+  (`.claude/skills/review-code/SKILL.md`) review pull requests that change code, contracts,
+  checks, or workflows against that rubric with Claude Code, with the same secret and app as
+  `docs-review`, and install no plugin.
+- Module `dual_review` (question `dual_review`, default off): the `dual-review` skill
+  (`.claude/skills/dual-review/SKILL.md`) reviews a branch before its pull request with a Claude
+  subagent and the Codex CLI in a read-only sandbox, after a passing `scripts/check.sh`, for at
+  most three rounds, without commits; its verdict goes under "Checks" in the description
+  (`docs/contributing.md`, sections 3 and 4).
+
+### Changed
+
+- `create-pr` skill: waits for and answers the `code-review` run next to `docs-review`, and with
+  the `dual_review` module runs the dual review when the branch has no verdict for its tree.
+- `docs/contributing.md`, section 3: every review comment is answered before the merge, from
+  either review workflow.
+- Linter configuration (`.markdownlint-cli2.jsonc`): in `CHANGELOG.md`, headings need to be
+  unique among siblings only, so that each version can have its own Added and Changed.
+- Seeded `docs/README.md`: rows for the testing rules and the review of pull requests, and the
+  planned "Review criteria" section. An existing project copies these rows by hand.
+
+## [0.2.0] - 2026-10-29
+
+### Changed
+
+- `create-pr` skill (`.claude/skills/create-pr/SKILL.md`), with the `docs_review` module: after
+  opening the pull request it waits for the `docs-review` run, answers every comment (a fix in
+  its own commit, a decline with a reason, or a question for the owner), records the outcome in
+  the description, and reports it; a draft or a run that does not finish is reported instead of
+  waited for. `docs/contributing.md`, section 4, names the new step.
+
+## [0.1.0] - 2026-10-29
+
+### Added
+
+- Agent rules (`AGENTS.md` with one project block, `CLAUDE.md`), documentation rules with file
+  ownership (`docs/documentation-rules.md`), contribution and template update rules
+  (`docs/contributing.md`), and the seeded documentation map (`docs/README.md`).
+- Short decision records: `docs/decisions/adr-template.md` and the generated index
+  `docs/decisions/README.md` (`scripts/gen-decisions-index.sh`).
+- Checks behind one entry point, `scripts/check.sh`: documentation (markdownlint-cli2, lychee),
+  decision records (integrity, next number, index, merge readiness), template integrity
+  (`.template/owned.sha256`), and project checks from `scripts/checks.d/`.
+- Claude Code hooks (protect, Stop checks, project Stop hooks from `.claude/hooks/project/stop/`)
+  and skills (`create-pr`, `update-template`, and `docs-review` as the `docs_review` module).
+- CI workflows `docs` (with Node.js set up), `decisions`, and `docs-review`, with the runner chosen
+  by a question and overridable by the repository variable `CI_RUNS_ON`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dev-oleksandrv and the contributors of xandronak/agent-docs-template
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# create-afe-project
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An npm package that creates agent-friendly repositories and keeps them up to date. It gives a new
+project its documentation rules, short decision records with a generated index, contribution and
+pull request rules, checks that run the same way locally, in Claude Code hooks, and in CI, and the
+Claude Code skills that apply them. It implements the pillars of
+[Agent-Friendly Engineering](https://github.com/dev-oleksandrv/afe/blob/main/GUIDE.md). Repository:
+`dev-oleksandrv/create-afe-project`; it started as a fork of the Copier template
+`xandronak/agent-docs-template`.
+
+## What a generated project gets
+
+| Part | Files |
+| --- | --- |
+| Agent rules | `AGENTS.md` with one project block, `CLAUDE.md` |
+| Testing rules: what a test is for and must prove | `docs/testing-rules.md` |
+| Documentation rules, statuses, and file ownership | `docs/documentation-rules.md`, `docs/README.md` |
+| Branches, commits, pull requests, template updates, review of pull requests | `docs/contributing.md` |
+| Decision records | `docs/decisions/adr-template.md`, a generated `docs/decisions/README.md` |
+| Checks and environment | `scripts/check.sh` and the scripts it runs, the link check `scripts/check-links.mjs` included; `scripts/env.sh` for the environment commands; `scripts/protect-branch.sh` for the GitHub ruleset of `main`; optional `scripts/check-acceptance.sh` and `scripts/fail-without-change.sh` |
+| Claude Code hooks, permissions, and skills | `.claude/settings.json` (generated): deny rules for secrets and destructive pushes; `.claude/hooks/`: the protect hook (asks before protected edits, publishing, and a known token format; denies a push to `main`), the check after every edit, and the Stop hooks; `.claude/skills/`: `afe-init` (sets up the code, its stack, and its checks with the owner), `create-pr`, `update-template`, optional `docs-review`, `review-code`, and `dual-review` |
+| CI | `.github/workflows/` (`docs`, `decisions`, optional `secret-scan`, `docs-review`, `code-review`, and `fail-without-change`) |
+
+Every file has one owner: the template, the project, or a generator. The rules are in
+[`template/docs/documentation-rules.md.jinja`](template/docs/documentation-rules.md.jinja),
+section 9.
+
+## Requirements
+
+Node.js 20 or later with npm, Git, and bash. A generated project needs nothing more: its hooks
+and checks, the link check included, run on Node.js.
+
+## Create a project
+
+```bash
+npm create afe-project@latest <directory>
+# or
+npx create-afe-project@latest <directory>
+```
+
+The wizard asks for the project name, a one-sentence description, the GitHub repository, the CI
+runner (GitHub-hosted, or a self-hosted Linux runner), whether pull requests get the Claude
+documentation review and code review, whether the review before a pull request adds the Santa
+loop (with the Codex CLI when it is installed, otherwise with two Claude subagents), whether CI
+scans every change for secrets with gitleaks, and whether to add the Acceptance check and the
+fail-without-change driver. It then writes the generated files and prints the next
+steps. Without a terminal, or with `--defaults`, it takes answers from `--data key=value` and
+`--data-file answers.json`, then the defaults:
+
+```bash
+npx create-afe-project@latest acme --defaults --data project_name=acme \
+  --data 'project_description=A sample project.' --data github_repo=acme/acme
+```
+
+`npx create-afe-project --help` lists every option.
+
+## Update a project
+
+In the project, the `update-template` skill does it, following the project's
+`docs/contributing.md`, section 5: a branch from a clean `main`, then
+
+```bash
+npx create-afe-project@latest update --defaults
+```
+
+It replaces the template-owned files, keeps the project block of `AGENTS.md`, creates missing
+seeded files and never changes existing ones, runs the migrations between the two versions, and
+regenerates the generated files; then the checks and a pull request. A project generated by the
+Copier template converts its `.copier-answers.yml` to `.afe-answers.json` on its first update.
+
+## Versions
+
+Releases are npm versions, tagged `vMAJOR.MINOR.PATCH` in Git and described in [`CHANGELOG.md`](CHANGELOG.md).
+How versions are chosen and released: [`docs/maintaining.md`](docs/maintaining.md).
+
+## License
+
+[MIT](LICENSE).

package/bin/create-afe-project.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// Command line of create-afe-project: create a project, or update one to this package's template.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import * as p from '@clack/prompts';
+import { UsageError } from '../src/answers.js';
+import { VERSION, create, update } from '../src/project.js';
+
+const HELP = `create-afe-project ${VERSION}
+
+Usage:
+  npm create afe-project@latest [directory] [-- options]
+  npx create-afe-project@latest [directory] [options]   create a project
+  npx create-afe-project@latest update [options]        update the project in the current directory
+
+Options:
+  --defaults           do not ask: take --data, then the recorded answers, then the defaults
+  --data key=value     answer a question; repeatable
+  --data-file <file>   answers from a JSON file; --data wins over it
+  --force              create: write into a directory that is not empty
+  --no-git             create: do not make the initial Git commit on main
+  --allow-dirty        update: run with uncommitted changes
+  --quiet              print only errors and the result
+  -h, --help           print this help
+  -v, --version        print the version
+`;
+
+function given(values) {
+  const data = values['data-file'] ? JSON.parse(readFileSync(values['data-file'], 'utf8')) : {};
+  for (const pair of values.data ?? []) {
+    const i = pair.indexOf('=');
+    if (i < 1) throw new UsageError(`--data expects key=value, got ${pair}`);
+    data[pair.slice(0, i)] = pair.slice(i + 1);
+  }
+  return Object.fromEntries(Object.entries(data).filter(([k]) => !k.startsWith('_')));
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      defaults: { type: 'boolean' },
+      data: { type: 'string', multiple: true },
+      'data-file': { type: 'string' },
+      force: { type: 'boolean' },
+      'no-git': { type: 'boolean' },
+      'allow-dirty': { type: 'boolean' },
+      quiet: { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+    },
+  });
+  if (values.help) return void process.stdout.write(HELP);
+  if (values.version) return void process.stdout.write(`${VERSION}\n`);
+
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !values.defaults;
+  const quiet = Boolean(values.quiet);
+  const common = { given: given(values), useDefaults: Boolean(values.defaults), interactive, quiet };
+  if (interactive) p.intro(`create-afe-project ${VERSION}`);
+
+  if (positionals[0] === 'update') {
+    if (positionals.length > 1) throw new UsageError('update takes no directory; run it in the project');
+    const r = await update(process.cwd(), { ...common, allowDirty: Boolean(values['allow-dirty']) });
+    const lines = [`Updated the template from ${r.from ?? 'an unrecorded version'} to ${r.to}.`];
+    if (r.legacy) lines.push('Converted .copier-answers.yml to .afe-answers.json.');
+    if (r.migrations.length) lines.push(`Migrations run: ${r.migrations.join(', ')}.`);
+    if (r.removed.length) lines.push(`Removed, no longer template-owned: ${r.removed.join(', ')}.`);
+    if (r.seeded.length) lines.push(`Created missing seeded files: ${r.seeded.join(', ')}.`);
+    if (r.unowned.length) lines.push(`Created files without an owner class (a template defect): ${r.unowned.join(', ')}.`);
+    if (r.edited.length) {
+      lines.push(`Replaced local edits of template-owned files; review them in git diff: ${r.edited.join(', ')}.`);
+    }
+    lines.push('Next: scripts/check.sh, then a pull request (docs/contributing.md, section 5).');
+    return void (interactive ? p.outro(lines.join('\n')) : console.log(lines.join('\n')));
+  }
+
+  if (positionals.length > 1) throw new UsageError('expected at most one directory');
+  let dir = positionals[0];
+  if (!dir) {
+    if (!interactive) throw new UsageError('name the directory to create the project in');
+    dir = await p.text({ message: 'Where should the project go? (a new or empty directory)', placeholder: 'my-project', validate: (v) => (v?.trim() ? undefined : 'Required') });
+    if (p.isCancel(dir)) {
+      p.cancel('Cancelled; nothing was written.');
+      process.exit(130);
+    }
+  }
+  if (interactive) {
+    p.note(
+      'A few questions about the project, then yes/no questions that turn optional checks on.\n' +
+        'Press Enter to keep a default. To change an answer later, run\n' +
+        'npx create-afe-project@latest update in the project.',
+    );
+  }
+  const spinner = interactive && !quiet ? p.spinner() : null;
+  let spinning = false;
+  const { message } = await create(resolve(dir), {
+    ...common,
+    force: Boolean(values.force),
+    git: !values['no-git'],
+    quiet: quiet || interactive,
+    // Start the spinner once: a second start() leaves its first timer running, and the process
+    // never exits.
+    log: (msg) => {
+      if (!spinner) return;
+      if (spinning) spinner.message(msg);
+      else spinner.start(msg);
+      spinning = true;
+    },
+  });
+  spinner?.stop('Generated files written');
+  if (interactive) p.outro(message);
+  else console.log(message);
+}
+
+main().catch((error) => {
+  if (error instanceof UsageError || error?.code?.startsWith?.('ERR_PARSE_ARGS')) {
+    console.error(`create-afe-project: ${error.message}\nRun create-afe-project --help for usage.`);
+    process.exit(2);
+  }
+  console.error(`create-afe-project: ${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "create-afe-project",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Create and update agent-friendly repositories: documentation rules, decision records, checks, and Claude Code hooks and skills.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-afe-project": "bin/create-afe-project.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "changeset": "changeset",
+    "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts && scripts/sync-self.sh"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dev-oleksandrv/create-afe-project.git"
+  },
+  "keywords": [
+    "create",
+    "scaffold",
+    "template",
+    "agents",
+    "claude-code",
+    "afe"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "nunjucks": "^3.2.4",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "1.0.1",
+    "@changesets/cli": "3.0.3"
+  }
+}