unitoo/website
1
0
Fork 1
Code Issues 1 Pull requests Packages 1 Activity Actions

docs(agents): upgrade Agent Foundry to b04e778 #82

Merged
claudiomaradonna merged 1 commit from chore/foundry-upgrade-b04e778 into master 2026-11-11 14:17:10 +01:00
Conversation 0 Commits 1 Files changed 108 +3700 -699
motoko commented 2026-11-11 14:12:55 +01:00
Collaborator
Copy link

Why

The agents that work on this site follow a policy, skills and settings
copied from Agent Foundry, which the repository last adopted at
05a1481. The source has moved 428 commits since: it splits the old
all-in-one workflow into skills an agent picks per request (feature,
bug fix, refactor, documentation, review), adds reviewers for security
and documentation, guards the main checkout against direct edits, and
keeps secret files away from Claude Code. Staying on the old copy means
each future upgrade grows harder to merge. The upgrade also follows the
source's relicensing to MIT No Attribution.

What changed

Before, an agent read one long AGENTS.md and five skills; now it
routes each request to a workflow skill, writes its documents into a
work folder under .plans/, and gets its change reviewed by change,
security and document reviewers before delivery. File edits in the main
checkout on master are refused by a hook, and shell scripts agents
write are checked with ShellCheck.

In Claude Code, the repository settings now deny reads of secret files
(.env*, keys, keystores, credentials) at every depth, run Bash in
Claude Code's sandbox, ask before agents edit their own configuration,
and deny the Workflow, ScheduleWakeup, ReportFindings and
ListAgents tools. The repository's own allow list is kept.

AGENTS.md takes the source's layout; the site's facts and gotchas
move to its Architecture, Set-up, Test, Quality gates and Project rules
sections. The Verify command becomes
make build && .agents/hooks/shellcheck.sh repo. The README Quick
start lists every prerequisite (Python 3, Git 2.48 or later, ShellCheck
and jq added), CONTRIBUTING.md describes the agent setup, Codex hook
trust and what the azkaban layer needs, and LICENSE.agent-foundry
with its README credit goes, since MIT No Attribution asks for neither.
A Forgejo pull request template is added.

Breaking for contributors: Verify and the agent hooks now need
ShellCheck and jq, and Codex runs the hooks only after each workstation
trusts them in /hooks.

How to verify

  1. Have Git 2.48 or later, Ruby 4.0.7 with Bundler, Node 24 with
    terser, Python 3, ShellCheck, jq, and Claude Code.
  2. Problem, on main: git clone ssh://git@git.unitoo.it/unitoo/website.git /tmp/site-check && cd /tmp/site-check && ls .agents/skills lists
    only brainstorm diagnose forge foundry-upgrade write-plan, and
    git show HEAD:.claude/settings.json | grep -c '"sandbox"' prints
    0.
  3. Solution, on the branch:
    git switch chore/foundry-upgrade-b04e778 && bundle install && make build && .agents/hooks/shellcheck.sh repo ends with
    shell check: 4 files clean; ls .agents/skills now includes
    implement-feature, fix-bug and deliver.
  4. Start claude in /tmp/site-check on master and ask it to
    "add a comment to the top of README.md". On main it edits the file;
    on the branch the main-checkout guard refuses the edit and the agent
    opens a worktree under .worktrees/ instead.

Checks run on the tip: Verify passes (build complete, shell check 4
files clean); Agent Foundry's verify-agent-config.sh reports the
configuration valid; git diff --check master is clean. Step 4 was not
run in a fresh session; the site was not checked visually, as the
change touches no page.

Considerations

Every Agent Foundry file is byte-identical to the source at b04e778
except the project sections of AGENTS.md, the settings' allow list,
.gitignore and the upgrade skill's Record, so the next upgrade
merges cleanly. Reviewers' later-round wording suggestions (Node 22
stated twice in CONTRIBUTING.md, the README's undefined "Verify
command", the Matomo rule now naming its tracked source) were set aside
as low.

## Why The agents that work on this site follow a policy, skills and settings copied from Agent Foundry, which the repository last adopted at `05a1481`. The source has moved 428 commits since: it splits the old all-in-one workflow into skills an agent picks per request (feature, bug fix, refactor, documentation, review), adds reviewers for security and documentation, guards the main checkout against direct edits, and keeps secret files away from Claude Code. Staying on the old copy means each future upgrade grows harder to merge. The upgrade also follows the source's relicensing to MIT No Attribution. ## What changed Before, an agent read one long `AGENTS.md` and five skills; now it routes each request to a workflow skill, writes its documents into a work folder under `.plans/`, and gets its change reviewed by change, security and document reviewers before delivery. File edits in the main checkout on `master` are refused by a hook, and shell scripts agents write are checked with ShellCheck. In Claude Code, the repository settings now deny reads of secret files (`.env*`, keys, keystores, credentials) at every depth, run Bash in Claude Code's sandbox, ask before agents edit their own configuration, and deny the `Workflow`, `ScheduleWakeup`, `ReportFindings` and `ListAgents` tools. The repository's own allow list is kept. `AGENTS.md` takes the source's layout; the site's facts and gotchas move to its Architecture, Set-up, Test, Quality gates and Project rules sections. The Verify command becomes `make build && .agents/hooks/shellcheck.sh repo`. The README Quick start lists every prerequisite (Python 3, Git 2.48 or later, ShellCheck and jq added), `CONTRIBUTING.md` describes the agent setup, Codex hook trust and what the azkaban layer needs, and `LICENSE.agent-foundry` with its README credit goes, since MIT No Attribution asks for neither. A Forgejo pull request template is added. Breaking for contributors: Verify and the agent hooks now need ShellCheck and jq, and Codex runs the hooks only after each workstation trusts them in `/hooks`. ## How to verify 1. Have Git 2.48 or later, Ruby 4.0.7 with Bundler, Node 24 with `terser`, Python 3, ShellCheck, jq, and Claude Code. 2. Problem, on main: `git clone ssh://git@git.unitoo.it/unitoo/website.git /tmp/site-check && cd /tmp/site-check && ls .agents/skills` lists only `brainstorm diagnose forge foundry-upgrade write-plan`, and `git show HEAD:.claude/settings.json | grep -c '"sandbox"'` prints `0`. 3. Solution, on the branch: `git switch chore/foundry-upgrade-b04e778 && bundle install && make build && .agents/hooks/shellcheck.sh repo` ends with `shell check: 4 files clean`; `ls .agents/skills` now includes `implement-feature`, `fix-bug` and `deliver`. 4. Start `claude` in `/tmp/site-check` on `master` and ask it to "add a comment to the top of README.md". On main it edits the file; on the branch the main-checkout guard refuses the edit and the agent opens a worktree under `.worktrees/` instead. Checks run on the tip: Verify passes (build complete, shell check 4 files clean); Agent Foundry's `verify-agent-config.sh` reports the configuration valid; `git diff --check master` is clean. Step 4 was not run in a fresh session; the site was not checked visually, as the change touches no page. ## Considerations Every Agent Foundry file is byte-identical to the source at `b04e778` except the project sections of `AGENTS.md`, the settings' allow list, `.gitignore` and the upgrade skill's Record, so the next upgrade merges cleanly. Reviewers' later-round wording suggestions (Node 22 stated twice in `CONTRIBUTING.md`, the README's undefined "Verify command", the Matomo rule now naming its tracked source) were set aside as low. 
Merge Agent Foundry from 05a1481 to b04e778 by three-way merge.

The source now ships workflow and action skills, work-file templates,
document-reviewer, security-reviewer and implementer subagents, OpenCode
adapters, a main-checkout guard and ShellCheck hooks, and a sandbox
helper. AGENTS.md takes the source's sections by question: the project
facts move to Architecture, Set-up, Test, Quality gates and Project
rules; Name, Purpose, the duplicated English-text rule and the memory
rules go. Verify gains the repository shell check.

.claude/settings.json takes the source's file, keeping the repository's
allow list; the tool denials, secret-file Read rules and Bash sandbox
were agreed explicitly. A Forgejo pull request template is added.

The README Quick start now lists every prerequisite, Python 3, Git 2.48,
ShellCheck and jq included, and CONTRIBUTING.md describes the agent
setup, Codex hook trust and the jail's needs. LICENSE.agent-foundry and
its credit go, since the source is now MIT No Attribution.
motoko force-pushed chore/foundry-upgrade-b04e778 from 813ca38996 to c71699f1ae
All checks were successful
Build image / build (push) Successful in 5m9s
Details
2026-11-11 14:15:20 +01:00 Compare
claudiomaradonna deleted branch chore/foundry-upgrade-b04e778 2026-11-11 14:17:19 +01:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
unitoo/website!82
No description provided.