From 14a5e4137143e2eb0e19fa1f0b471e30dc7fcde8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olu=CC=81was=CC=A3e=CC=80yi=CC=81=20S=CC=A3o=CC=81bande?= =?UTF-8?q?=CC=81?= Date: Tue, 20 Oct 2026 19:48:01 +0100 Subject: [PATCH] docs: describe agent workflow roles without private names Replace the private repository name, its links, skill names and issue references with role descriptions. No rule, default or entry status changes. --- .changeset/neutral-agent-workflow-names.md | 5 +++++ AGENTS.md | 2 +- CHANGELOG.md | 4 ++-- README.md | 10 +++++----- skills/tech-stack/SKILL.md | 4 ++-- skills/tech-stack/references/layouts/repository.md | 2 +- skills/tech-stack/references/practices/agents.md | 2 +- skills/tech-stack/references/practices/architecture.md | 2 +- skills/tech-stack/references/practices/ci.md | 6 +++--- skills/tech-stack/references/practices/hooks.md | 6 +++--- skills/tech-stack/references/practices/testing.md | 2 +- 11 files changed, 25 insertions(+), 20 deletions(-) create mode 100644 .changeset/neutral-agent-workflow-names.md diff --git a/.changeset/neutral-agent-workflow-names.md b/.changeset/neutral-agent-workflow-names.md new file mode 100644 index 0000000..862a9ff --- /dev/null +++ b/.changeset/neutral-agent-workflow-names.md @@ -0,0 +1,5 @@ +--- +"tech-stack": patch +--- + +Describe the agent workflow skills by role instead of naming a private repository, its skills, links or issues. No rule, default or entry status changes. diff --git a/AGENTS.md b/AGENTS.md index 2ee1c82..71bb0e5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ Projects may change these defaults for a recorded reason. ## Focus - tech-stack recommends what a project uses: its tools, dependencies, layout, checks and CI. - It does not manage machines or dev resources. Shared local servers, per-app logins, `*.localhost` names and build reuse across worktrees belong to [local-services](https://github.com/quantipixels/local-services); point to it, never restate it. -- How agents work, and whether a gate earns its cost, belong to Alárinà (`idena`, `ipile`). tech-stack owns only the mechanics. +- How agents work, and whether a gate earns its cost, belong to the agent workflow skills it is used with. tech-stack owns only the mechanics. - Leave out what tools already do by default, such as machine-wide caches. A project-level choice that differs (pnpm over npm, `org.gradle.caching=true`) belongs here. - Ship a script only when a step changes state, deletes data, must be exact every time, or works through a lot of data. Steps an agent could type itself go in the references as `bash` templates. diff --git a/CHANGELOG.md b/CHANGELOG.md index 149d95f..cc7e8cc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,9 +16,9 @@ - d75e05e: Local tests that need a service use the shared local-services skill instead of a per-project compose stack. - 0ec7c63: Require declared MCP caller access, tool effects, readable failures and bounded instructions for TypeScript servers. - c7f9306: Document stable per-PR concurrency, job-level draft guards, ready/draft triggers, reusable-workflow key isolation and safe cleanup when path filters prevent cancellation runs. -- 7c62ff6: Narrow drills to what only they can prove. Lock-wait and race behavior needs a drill for each distinct race ordinary tests cannot exercise; plain authorization rules are ordinary tests. Ordinary drill databases are cloned from one migrated template, while migration and bootstrap tests keep their real starting state. A security reset gets one ordinary test per session kind, plus a real round-trip drill only when the accepted behavior includes restoring a real database. Alárinà owns proof scope and retirement, and the async-conversion rules apply only during that conversion. Playwright records traces only on retry or in a diagnostic rerun and gives tests that change server state per-worker accounts. Dialyzer is added only when the project relies on typespecs the compiler's inference does not check. +- 7c62ff6: Narrow drills to what only they can prove. Lock-wait and race behavior needs a drill for each distinct race ordinary tests cannot exercise; plain authorization rules are ordinary tests. Ordinary drill databases are cloned from one migrated template, while migration and bootstrap tests keep their real starting state. A security reset gets one ordinary test per session kind, plus a real round-trip drill only when the accepted behavior includes restoring a real database. The agent workflow skills own proof scope and retirement, and the async-conversion rules apply only during that conversion. Playwright records traces only on retry or in a diagnostic rerun and gives tests that change server state per-worker accounts. Dialyzer is added only when the project relies on typespecs the compiler's inference does not check. - 58d5a56: Run this public repository on GitHub-hosted runners and reserve label-routed self-hosted runners for private repositories, excluding forks. -- 4c6ec65: Link gate decisions and CI-depth selection to Alárinà; own hook and gate mechanics here, including Git environment isolation and SSH keepalive. +- 4c6ec65: Point gate decisions and CI-depth selection to the agent workflow skills; own hook and gate mechanics here, including Git environment isolation and SSH keepalive. - 5271aa7: Select TypeScript checks from source files rather than tooling-only manifests. - b9c61c5: Document Knip's low-memory CI setting and require passing/failing tests for custom lint rules, learned from SIGIDI and Ǹkan. - 94fc416: Allow Vite+ hooks in Vite+-only repositories and use vp staged for Vite+ pre-commit checks. Audits accept either hook manager. diff --git a/README.md b/README.md index 74839dc..dc568e2 100644 --- a/README.md +++ b/README.md @@ -11,17 +11,17 @@ Projects start from these choices instead of re-deciding them, and deviate when ## Works with -[Alárinà](https://github.com/quantipixels/alarina) routes how agents work; tech-stack answers what to build with. +The agent workflow skills it is used with route how agents work; tech-stack answers what to build with. agent-setup installs both. -Alárinà's `alarina` owns project record locations, and `ilana` owns writing agent-facing text. -Stack and tooling lessons from `ironu` reach tech-stack's maintainers as suggestions through a user-approved issue or PR. +Those workflow skills own project record locations and the writing of agent-facing text. +Stack and tooling lessons captured by the workflow skills reach tech-stack's maintainers as suggestions through a user-approved issue or PR. ## Non-goals - Product or domain decisions. - Generic advice that only restates tool defaults, tool descriptions, installation steps or flag lists; official docs own those. - Project-specific policy; keep it in that project's records, such as `CODEBASE_STANDARD.md`. -- Agent workflows, record-keeping procedures or agent-text writing methods; Alárinà owns those. +- Agent workflows, record-keeping procedures or agent-text writing methods; the agent workflow skills own those. ## Checks @@ -37,5 +37,5 @@ See [AGENTS.md](AGENTS.md) for reference authoring rules. Run `mise install` and `npm ci` to install the pinned tools, Changesets and hooks. Each change carries a changeset; merges to `ori` update the version PR, whose merge generates `CHANGELOG.md` and bumps both host manifests. Set `CHANGESETS_TOKEN` to let the version PR trigger checks; with `GITHUB_TOKEN`, a maintainer must trigger/approve its checks as needed. -Alárinà's marketplace lists this independent repository for both hosts; no copied skill or extra publishing step is needed. +The agent workflow marketplace lists this independent repository for both hosts; no copied skill or extra publishing step is needed. Host caches refresh only after the version PR merges and users update their plugins. diff --git a/skills/tech-stack/SKILL.md b/skills/tech-stack/SKILL.md index ca05bc6..7c5979f 100644 --- a/skills/tech-stack/SKILL.md +++ b/skills/tech-stack/SKILL.md @@ -11,7 +11,7 @@ Deviate when a project's real need makes another choice better, and record why i These entries are a floor, not the whole list. For each platform a project uses (a language, framework, host, store or CI service), also take the steps its own maintainers publish as standard, after checking their current docs. When planning, or when a choice is still open, research the options first, then present the user with a short recommendation and its alternatives instead of deciding silently. Precedence: the project's active instructions and records win over this skill; the user's explicit choice wins over both. -Tech-stack owns stack, tooling, code layout and architecture choices; Alárinà owns how agents work. +Tech-stack owns stack, tooling, code layout and architecture choices; how agents work belongs to the agent workflow skills it is used with. ## Read only what the task needs @@ -52,4 +52,4 @@ Official docs are linked from each entry. ## When a choice changes Project deviations stay in that project's records. -Changes to shared defaults go to tech-stack's maintainers as a user-approved issue or PR; stack and tooling lessons from Alárinà's `ironu` arrive as suggestions. +Changes to shared defaults go to tech-stack's maintainers as a user-approved issue or PR; stack and tooling lessons captured by the agent workflow skills arrive as suggestions. diff --git a/skills/tech-stack/references/layouts/repository.md b/skills/tech-stack/references/layouts/repository.md index e53a0f1..b9ee7f4 100644 --- a/skills/tech-stack/references/layouts/repository.md +++ b/skills/tech-stack/references/layouts/repository.md @@ -15,7 +15,7 @@ One repository per product, polyglot when needed. ``` Agent instruction files follow [the agent instructions default](../practices/agents.md). ## Docs and records -Alárinà's `alarina` owns record locations; existing locations (including `docs/adr/`, `docs/solutions/` and `.nongoals`) win and are kept. +The agent workflow owns record locations; existing locations (including `docs/adr/`, `docs/solutions/` and `.nongoals`) win and are kept. Its defaults: lessons in `docs/internal/solutions//`, decisions in `docs/internal/decisions/`, runbooks (deploy, backup, restore, observability) in `docs/internal/operations/`, user guides in `docs/user/`, and non-goals in the README's "Non-goals" section. ## Rules diff --git a/skills/tech-stack/references/practices/agents.md b/skills/tech-stack/references/practices/agents.md index 97c373c..69b77b3 100644 --- a/skills/tech-stack/references/practices/agents.md +++ b/skills/tech-stack/references/practices/agents.md @@ -10,4 +10,4 @@ verified: 2026-10-18 · https://code.claude.com/docs/en/memory#share-one-file-wi - Keep project facts (paths, versions, numbers) in the repo's records; agent definitions point to those records. - Codex spawns a custom agent only when told. When a host tool such as `delegate_task` cannot pick one, brief: "Act as the role defined in ``; read it first." For Claude-side work, call the agent by name (`@`). - For an agent the main session should pick without being named, start its description with "Use proactively." Leave on-demand agents (reviewers, auditors) without it. -- Writing agent instructions and descriptions follows Alárinà's `ilana` when installed; the host owns agent selection and invocation. +- Writing agent instructions and descriptions follows the agent workflow's method for writing agent-facing text when installed; the host owns agent selection and invocation. diff --git a/skills/tech-stack/references/practices/architecture.md b/skills/tech-stack/references/practices/architecture.md index b900442..a282c22 100644 --- a/skills/tech-stack/references/practices/architecture.md +++ b/skills/tech-stack/references/practices/architecture.md @@ -21,4 +21,4 @@ - Agent instruction files follow [the agent instructions default](agents.md#agent-instructions--default-over-a-claudemd-import-with-claude-only-lines). - Non-goals in a README "Non-goals" section or an existing `.nongoals` file. - Recommend `ARCHITECTURE.md` when a module map and boundaries need explanation, and `CODEBASE_STANDARD.md` when rules the tools do not yet enforce need a shared reference. -- Decisions and real lessons follow the project's existing locations or Alárinà's `alarina` defaults summarized in `../layouts/repository.md`; create records only when there is something to keep. +- Decisions and real lessons follow the project's existing locations or the agent workflow's default record locations, summarized in `../layouts/repository.md`; create records only when there is something to keep. diff --git a/skills/tech-stack/references/practices/ci.md b/skills/tech-stack/references/practices/ci.md index 1a2f286..503d394 100644 --- a/skills/tech-stack/references/practices/ci.md +++ b/skills/tech-stack/references/practices/ci.md @@ -1,6 +1,6 @@ # CI (GitHub Actions) -Before designing gates, check the plan: GitHub Free private repos cannot require checks (see Learned), so CI there is advisory. Size gates and their self-tests to what the plan can enforce; Alárinà's `idena` decides whether a gate earns its cost. +Before designing gates, check the plan: GitHub Free private repos cannot require checks (see Learned), so CI there is advisory. Size gates and their self-tests to what the plan can enforce; the agent workflow's method for deciding whether a gate is worth adding settles whether it earns its cost. ### actionlint — required verified: 2026-10-06 · https://github.com/rhysd/actionlint ### zizmor — required @@ -13,7 +13,7 @@ verified: 2026-10-06 · https://docs.zizmor.sh - For PR checks, follow [PR run efficiency](ci-pr-checks.md): cancel superseded runs and skip check jobs while the PR is a draft. The merge-gating job reports on every non-draft `pull_request` head. - Filter expensive jobs by path inside an unfiltered PR workflow; add an aggregator with `if: always() && github.event.pull_request.draft != true` that succeeds for intentional skips and fails for failures or cancellations. - With CI limited to PRs and default-branch pushes, branch pushes without a ready PR get no checks. Open a draft PR early for tracking; mark it ready when checks should begin, or run local checks while drafting. -- Select slow lanes using Alárinà's `ipile` [CI-depth design](https://github.com/quantipixels/alarina/blob/ori/plugins/software-eng/skills/ipile/references/ci-depth.md). Before splitting jobs, selecting tests, caching or sharding, research and measure, then choose from the optional [CI options](ci-options.md). +- Select slow lanes using the agent workflow's CI-depth method. Before splitting jobs, selecting tests, caching or sharding, research and measure, then choose from the optional [CI options](ci-options.md). - Every checked-in generated artifact (WASM, generated clients, generated validators) has a freshness job: regenerate, then `git diff --exit-code`. - When output depends on the build host (Rust `wasm32` bytes differ between aarch64 and x86_64, [cargo#8140](https://github.com/rust-lang/cargo/issues/8140)), byte-compare fails. Check in a stamp holding a hash of the inputs (sources, lockfile, toolchain, build script) and of the output instead; the job fails when either hash no longer matches, and the artifact is rebuilt only when inputs change. - Size matrices to real runner capacity: parallel jobs on one runner queue behind each other, so one concurrent job can finish sooner. @@ -29,7 +29,7 @@ verified: 2026-10-06 · https://docs.zizmor.sh - When `/tmp` is a small tmpfs, a [job-started hook](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/run-scripts) (`ACTIONS_RUNNER_HOOK_JOB_STARTED`) points `TMPDIR`, `TMP` and `TEMP` at `RUNNER_TEMP` through `$GITHUB_ENV`; the runner [empties `RUNNER_TEMP`](https://docs.github.com/en/actions/reference/workflows-and-actions/variables) itself. A hook's non-zero exit fails the job, so make the hook fail open: log and exit 0. Changing the hook path needs a runner restart, which kills the running job when the unit uses `KillMode=control-group` ([systemd's default](https://www.freedesktop.org/software/systemd/man/latest/systemd.kill.html); the runner's [stock unit](https://github.com/actions/runner/blob/main/src/Misc/layoutbin/actions.runner.service.template) uses `process`), so restart only when no job can be running. ## Base-ref gates -Alárinà's `idena` owns [whether to add a gate and when it retires](https://github.com/quantipixels/alarina/blob/ori/plugins/software-eng/skills/idena/SKILL.md); `ironu` hands findings to it. Build an accepted gate as follows, running from the base on `pull_request_target`. +The agent workflow's gate-decision method owns whether to add a gate and when it retires, and its lesson capture hands findings to that method. Build an accepted gate as follows, running from the base on `pull_request_target`. - Read the head only as git data (`git cat-file`, `git diff`, `git ls-tree`); parse text, never eval. Never check it out or run its `mix`, `npm`, `make`, hooks or scripts, including a head copy of the gate. - Exceptions and baselines come only from base files, each with file, identity and reason; ignore entries without a reason or present only in the head. Tool versions come from the base lockfile. - `permissions: {}` with `contents: read` per job, `persist-credentials: false`, actions pinned by SHA. Fetch `refs/pull/N/head` as objects and check it equals the event's head SHA. diff --git a/skills/tech-stack/references/practices/hooks.md b/skills/tech-stack/references/practices/hooks.md index 9e23067..d56bc73 100644 --- a/skills/tech-stack/references/practices/hooks.md +++ b/skills/tech-stack/references/practices/hooks.md @@ -24,7 +24,7 @@ verified: 2026-10-15 · https://github.com/evilmartians/lefthook · https://vite | Dependency, licence and vulnerability scanning | CI | | Workflow, container and shell config linting | CI | | Security static analysis | CI | -| Slow lanes (end-to-end, drills, database interleaving) | CI; see Alárinà's `ipile` CI-depth design linked in `ci.md` | +| Slow lanes (end-to-end, drills, database interleaving) | CI; see the agent workflow's CI-depth method referenced in `ci.md` | | Base-ref gates, OS matrices, checks needing CI-only secrets | CI | - In an existing repo, hooks call its existing check entry point; adding tools from this skill is a separate change the owner asks for. - `check` proves the code passes; proving the change works on the running product is verification, done by the agent after the build, not in hooks. @@ -35,6 +35,6 @@ verified: 2026-10-15 · https://github.com/evilmartians/lefthook · https://vite ## Rules - Hooks call mise tasks or tools pinned in `mise.toml`; never a tool from the global PATH. - A hook never rewrites files the user did not stage. -- Gate launchers clear inherited `GIT_*` variables before tests; fixture helpers also drop every inherited `GIT_*` variable from Git subprocess environments. Git's hook environment can redirect a disposable repository's operations into the real checkout (Alárinà #122). -- Keep pre-push fast or add `-o ServerAliveInterval=30` to the existing SSH command, preserving its identity and proxy options: Git opens the connection before hooks run (Alárinà #122). +- Gate launchers clear inherited `GIT_*` variables before tests; fixture helpers also drop every inherited `GIT_*` variable from Git subprocess environments. Git's hook environment can redirect a disposable repository's operations into the real checkout (seen when tests run under a pre-push hook emptied the real index and committed fixture files onto the current branch). +- Keep pre-push fast or add `-o ServerAliveInterval=30` to the existing SSH command, preserving its identity and proxy options: Git opens the connection before hooks run (seen when a 7-minute pre-push gate passed, but the host had closed the idle connection and the push failed). - Skipping a hook (`--no-verify`) is the user's call only; agents do not skip hooks. diff --git a/skills/tech-stack/references/practices/testing.md b/skills/tech-stack/references/practices/testing.md index a4e3a4a..73d06b9 100644 --- a/skills/tech-stack/references/practices/testing.md +++ b/skills/tech-stack/references/practices/testing.md @@ -24,7 +24,7 @@ - Lock-wait and race behavior needs a database interleaving drill, because a sandboxed test cannot race; plain authorization rules are ordinary tests. Drill each distinct race that ordinary tests cannot exercise, and merge cases that would catch the same failure. - Clone ordinary drill databases from one migrated template (`CREATE DATABASE … TEMPLATE`) instead of migrating from zero per test or module; migration and bootstrap tests start from their real starting state. - A security reset (epoch restore, credential generation, password change) has one ordinary test per session kind, plus a real round-trip drill when the accepted behavior includes restoring a real database. -- Alárinà owns proof scope and retirement. The async-conversion rules in `elixir-phoenix` (zero unmapped losses, never loosen an assertion) apply only during that conversion. +- The agent workflow skills own proof scope and retirement. The async-conversion rules in `elixir-phoenix` (zero unmapped losses, never loosen an assertion) apply only during that conversion. - A test that only one machine can run is not proof; it runs in CI or in `check:full`. - A fixture that runs git drops every inherited `GIT_*` variable and passes its own repo path, so it cannot reach the real repo when a hook runs it (see [hooks](hooks.md#rules)).