From 50e1f165fd1196c5202bad6bd12077645b4e4f1f Mon Sep 17 00:00:00 2001 From: xormania <127287135+xormania@users.noreply.github.com> Date: Tue, 1 Sep 2026 12:07:59 -0400 Subject: [PATCH 1/9] agents: adopt the maintainer-directed lane; unpin the model; add the Claude pointer AGENTS.md replaces the total git/GitHub prohibition with the maintainer-directed lane (org CONTRIBUTING.md, decision of 2026-09-01): agents branch, commit, push, and open draft PRs under maintainer direction with origin trailers; merging, releasing, and settings remain the maintainer's. Content boundaries, supply-chain, secret, naming, and positioning rules are preserved; the file no longer names a server runtime, per the runtime supersession. Root CLAUDE.md is added because Claude Code does not load AGENTS.md on its own. .codex/config.toml drops its model pins: the model is supplied at dispatch, never by repository config. README gains the boundary/contribution-posture unsplice (the posture paragraphs had been inserted mid-list, orphaning the closing line). Skills: the inspect-first pair aligns its git rule with the lane; the safe-repo-change pair stops naming a server runtime. Source: owner 2026-09-01 Source: original Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XehTac5TJNmPAskwrPp7rJ --- .agents/skills/inspect-first/SKILL.md | 2 +- .agents/skills/safe-repo-change/SKILL.md | 2 +- .claude/skills/inspect-first/SKILL.md | 2 +- .claude/skills/safe-repo-change/SKILL.md | 2 +- .codex/config.toml | 10 +- AGENTS.md | 798 ++--------------------- CLAUDE.md | 7 + README.md | 9 +- 8 files changed, 66 insertions(+), 766 deletions(-) create mode 100644 CLAUDE.md diff --git a/.agents/skills/inspect-first/SKILL.md b/.agents/skills/inspect-first/SKILL.md index 714caee..c099bc5 100644 --- a/.agents/skills/inspect-first/SKILL.md +++ b/.agents/skills/inspect-first/SKILL.md @@ -21,7 +21,7 @@ Build a grounded view of the repository before acting. Do not infer repository s - Do not run Symfony commands. - Do not run Docker builds. - Do not generate local artifacts. -- Do not stage, commit, push, merge, tag, or release. +- Do not stage, commit, or push outside a task the maintainer directed (see AGENTS.md, maintainer-directed lane). Never merge, tag, or release. - Do not create broad refactors when the user asked for a bounded change. - Do not revive old retired namespace language. If encountered, flag it as a cleanup issue. diff --git a/.agents/skills/safe-repo-change/SKILL.md b/.agents/skills/safe-repo-change/SKILL.md index f86a0ed..4eb0107 100644 --- a/.agents/skills/safe-repo-change/SKILL.md +++ b/.agents/skills/safe-repo-change/SKILL.md @@ -33,7 +33,7 @@ Make the smallest correct change that satisfies the user’s request while prese For `minspec/skeleton`, preserve the minimal skeleton purpose: - minimal Symfony application baseline -- Symfony Docker / FrankenPHP / Caddy runtime baseline +- the server runtime baseline lives in `minspec/docker`, not here - no database requirement by default - no default UX/application layer - no Workbench implementation diff --git a/.claude/skills/inspect-first/SKILL.md b/.claude/skills/inspect-first/SKILL.md index babc895..50f7bc5 100644 --- a/.claude/skills/inspect-first/SKILL.md +++ b/.claude/skills/inspect-first/SKILL.md @@ -23,7 +23,7 @@ Build a grounded view of the repository before acting. Do not infer repository s - Do not run Symfony commands. - Do not run Docker builds. - Do not generate local artifacts. -- Do not stage, commit, push, merge, tag, or release. +- Do not stage, commit, or push outside a task the maintainer directed (see AGENTS.md, maintainer-directed lane). Never merge, tag, or release. - Do not create broad refactors when the user asked for a bounded change. - Do not revive old retired namespace language. If encountered, flag it as a cleanup issue. diff --git a/.claude/skills/safe-repo-change/SKILL.md b/.claude/skills/safe-repo-change/SKILL.md index 126b8d9..8474524 100644 --- a/.claude/skills/safe-repo-change/SKILL.md +++ b/.claude/skills/safe-repo-change/SKILL.md @@ -35,7 +35,7 @@ Make the smallest correct change that satisfies the user’s request while prese For `minspec/skeleton`, preserve the minimal skeleton purpose: - minimal Symfony application baseline -- Symfony Docker / FrankenPHP / Caddy runtime baseline +- the server runtime baseline lives in `minspec/docker`, not here - no database requirement by default - no default UX/application layer - no Workbench implementation diff --git a/.codex/config.toml b/.codex/config.toml index fdb661e..f1a3869 100644 --- a/.codex/config.toml +++ b/.codex/config.toml @@ -4,11 +4,9 @@ # Keep secrets, auth, provider routing, profiles, telemetry, and machine-local paths # in ~/.codex/config.toml, not in this repository. -model = "gpt-5.5" -review_model = "gpt-5.5" - -# Strong enough for repo edits and doctrine-sensitive review without using -# experimental maximum reasoning by default. +# No model pin. The model is supplied at dispatch or session start, never named +# by a repository config (maintainer rule, 2026-09-01). Reasoning defaults below +# apply to whatever model the session runs. model_reasoning_effort = "high" model_reasoning_summary = "concise" model_verbosity = "medium" @@ -89,4 +87,4 @@ terminal_title = ["spinner", "project"] # uncomment this table. Leave it commented for WSL/Linux/Chromebook. # # [windows] -# sandbox = "elevated" \ No newline at end of file +# sandbox = "elevated" diff --git a/AGENTS.md b/AGENTS.md index 787cb4b..a6693b7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,795 +6,87 @@ This repository is `minspec/skeleton`. `minspec/skeleton` is the pure Composer/Flex Symfony application skeleton for MinSpec projects. -It is not the Docker runtime repository. Docker Compose, Dockerfiles, Caddy/FrankenPHP configuration, docker-entrypoint scripts, and first-run Docker bootstrap behavior belong in `minspec/docker`. +It is not the Docker runtime repository. Docker Compose, Dockerfiles, server runtime configuration, docker-entrypoint scripts, and first-run Docker bootstrap behavior belong in `minspec/docker`. -## Hard boundaries -Agents may assist the maintainer. -Agents do not decide project direction. -Agents do not control Git. -Agents do not control GitHub. -Agents do not create pull requests. -Agents do not mutate repository authority. +## Operating mode: maintainer-directed agent work -## Instruction Precedence +Agents work in this repository under the maintainer-directed lane defined in the org `CONTRIBUTING.md` (Maintainer-Directed Agent Work, maintainer decision 2026-09-01): -These instructions apply to: +- The maintainer directs the work and names its scope. Undirected work does not start. +- Agents may branch, commit, push, and open **draft** pull requests through accounts the maintainer granted. +- Every commit carries origin trailers: `Source:` (where the content came from — `original`, a `repo@sha` pointer, a URL, `owner `, or `generated: `) and `Co-Authored-By:` naming the specific model that did the work, vendor noreply address. Work an agent did not do gets no trailer with its name. +- Author and committer identity remain the maintainer's; agent credit lives in the trailers. +- Agents never approve, merge, ratify, tag, release, publish, or change repository settings, protections, secrets, workflows-permissions, or collaborator access. Ratification is the maintainer's act, always. +- Agents never rewrite history, never force-push, and never delete branches — branches are part of the record. +- Reviews from other agents are welcome: findings go in PR comments; a commit fixing a reviewer's finding may credit the reviewer with a `Reviewed-by:` trailer. -- Codex CLI -- Codex VS Code extension -- Claude Code -- Claude Desktop / Claude agent workflows -- Gemini agent workflows -- Cursor -- Copilot -- local MCP-enabled agents -- any other coding, review, or repository-maintenance agent operating in this repository - -Tool-specific instruction files such as `.codex/config.toml`, `.codex/AGENTS.md`, `.claude/CLAUDE.md`, skills, prompts, or MCP instructions may add stricter rules. - -They MUST NOT weaken this file. - -If instructions conflict, follow this order: +Instruction precedence, when anything conflicts: 1. explicit maintainer instruction for the current task -2. this `AGENTS.md` -3. tool-specific instruction files +2. this `AGENTS.md` (with the org `CONTRIBUTING.md` and `GOVERNANCE.md` behind it) +3. tool-specific instruction files (`CLAUDE.md`, `.codex/config.toml`, skills) 4. general model behavior or defaults -However, explicit maintainer instruction does not imply permission to perform GitHub-visible actions unless the maintainer specifically names the exact action. - -A request such as “prepare a PR” means prepare local changes and PR text for human review. -It does not mean create the pull request. - -Do not add Docker artifacts to this repository: - -- no `compose.yaml` -- no `compose.override.yaml` -- no `compose.prod.yaml` -- no `Dockerfile` -- no `Caddyfile` -- no `frankenphp/` -- no Docker entrypoint scripts +Tool-specific files may add stricter rules; they must not weaken this file. -Do not add generated Symfony application files to this repository unless explicitly requested: +## What this repository holds — and refuses -- no committed `.env` -- no committed `bin/` -- no committed `config/` -- no committed `public/` -- no committed `src/` -- no committed `tests/` -- no committed `composer.lock` -- no committed `symfony.lock` +This repository remains a Composer/Flex seed. Do not add Docker artifacts: -This repository should remain a Composer/Flex seed. +- no `compose.yaml`, `compose.override.yaml`, `compose.prod.yaml` +- no `Dockerfile`, no server runtime configuration, no entrypoint scripts -## Allowed work +Do not add generated Symfony application files unless explicitly requested: -Appropriate changes include: +- no committed `.env`, `bin/`, `config/`, `public/`, `src/`, `tests/` +- no committed `composer.lock` or `symfony.lock` -- `composer.json` metadata and dependency constraints -- README / documentation -- repository policy files -- source-control hygiene files -- Packagist-facing metadata -- MinSpec skeleton doctrine +Appropriate changes: `composer.json` metadata and constraints, README and documentation, repository policy files, source-control hygiene files, Packagist-facing metadata, MinSpec skeleton doctrine. ## Testing discipline -Do not generate local install/build/runtime artifacts inside this repository while making source edits. - -To test `composer create-project`, use a scratch directory outside the repository, for example: - -```bash -mkdir -p ~/projects/_scratch -cd ~/projects/_scratch -rm -rf minspec-skeleton-test -composer create-project minspec/skeleton minspec-skeleton-test --prefer-dist -``` - -Inspect results there, not inside this repository. - -## Source-of-truth discipline - -Make changes through pull requests. Keep changes small and reviewable. - -Before proposing edits, classify the file or behavior as one of: - -- Composer/Flex skeleton seed -- generated Symfony application output -- Docker/runtime bootstrap -- repository governance/docs - -Only modify the layer that owns the behavior. -- the maintainer is the only approved contributor unless explicitly stated otherwise -- unsolicited third-party code contribution is not part of the workflow -- human review is mandatory -- no agent may approve, merge, release, tag, publish, or create pull requests -- no agent may open, close, label, edit, assign, or comment on GitHub issues -- no agent may change repository settings, permissions, protections, secrets, or workflows -- AI assistance does not transfer authority from the maintainer to the tool - -Do not write contribution language implying that outside pull requests are generally welcome. - -Use maintainer-assistance language, not community-governance language. - -## Core Doctrine for This Package - -Agents MUST preserve these principles: - -- MinSpec favors package-first composition. -- Applications are composed deliberately. -- The skeleton must remain minimal. -- Higher-level capabilities belong in installable packages, recipes, adapters, Workbench, or project-level decisions. -- Deterministic install-time wiring is preferred over hidden magic. -- Source-of-truth discipline matters. -- AI may assist development, but AI does not own doctrine, commits, releases, pull requests, issues, merge authority, or repository governance. - -Do not expand this file into a full doctrine manifesto. - -## Agent Operating Rules - -Before editing, agents MUST inspect the repository and understand the requested scope. - -Agents MUST: - -- inspect before editing -- keep changes PR-sized -- preserve the purpose of this repository -- prefer source-only, metadata-only, and documentation-only changes unless implementation is explicitly requested -- make the smallest change that satisfies the task -- report ambiguity before acting on it -- distinguish facts from assumptions -- preserve existing repository patterns unless explicitly asked to change them -- stop when a task conflicts with this file or the package purpose -- treat GitHub, Git history, issues, pull requests, releases, and repository settings as human-controlled surfaces - -Agents MUST NOT: - -- silently broaden task scope -- introduce new doctrine beyond the requested change -- invent package architecture -- add dependencies unless explicitly requested -- remove dependencies unless explicitly requested -- update lock files unless explicitly requested -- generate local build/runtime artifacts unless explicitly requested -- change licensing unless explicitly requested -- alter release, registry, branch-policy, or GitHub assumptions without explicit instruction -- normalize agent autonomy over human review -- use GitHub as an action surface -- treat issue or PR operations as routine agent work - -## Hard Prohibitions - -Agents MUST NOT include, revive, or reference: - -- retired predecessor namespaces -- retired project names -- non-MinSpec branding -- migration history -- old repository ownership history -- generalized Workbench doctrine -- Symfony Mate/MCP doctrine inside this skeleton -- SaaS doctrine -- unrelated project doctrine -- semantic theory or research doctrine -- generic AI hype -- broad “software factory” positioning - -Agents MUST NOT make public claims that exceed what this package actually does. - -## Source and Supply-Chain Policy - -Code provenance matters. - -Acceptable sources for code patterns are limited to: - -- official upstream documentation -- official upstream repositories -- existing code already present in this repository -- approved MinSpec repositories -- explicit maintainer-provided instructions - -Agents MUST NOT: - -- paste third-party code from blogs, tutorials, Stack Overflow, random GitHub repositories, or unapproved snippets -- add packages casually -- add Composer plugins casually -- add GitHub Actions casually -- add Docker images casually -- add remote scripts casually -- add external templates casually -- add generated code from uncontrolled sources - -Any change to dependencies, Composer plugins, Docker images, GitHub Actions, external tools, or package metadata is high-risk and requires explicit maintainer approval. - -Treat supply-chain changes as security-sensitive even when they appear routine. - -## Secret, Credential, and Authority Boundary - -Agents MUST NOT inspect, print, copy, modify, or rely on secrets or credentials. - -Agents MUST NOT read or expose: - -- GitHub tokens -- Packagist tokens -- Composer auth files -- SSH private keys -- `.env.local` -- `.env.*.local` -- `auth.json` -- `.npmrc` tokens -- `~/.ssh` -- `~/.git-credentials` -- `~/.config/gh` -- `~/.codex` -- `~/.claude` -- shell history -- credential helper output -- environment variables likely to contain secrets - -Agents MUST NOT ask the maintainer to paste secrets into chat. - -Agents MUST NOT use credentials to perform repository actions. - -If a task appears to require credentials, stop and explain that the human maintainer must perform that step. - -## Command Policy - -Agents may recommend commands, but MUST distinguish recommended commands from commands actually run. - -Agents MUST prefer read-only inspection commands. - -Agents MUST NOT run commands that: - -- mutate Git state -- mutate GitHub state -- create pull requests -- create, edit, comment on, close, label, assign, or milestone issues -- push branches -- create tags -- create releases -- change branch protection -- change repository settings -- change GitHub Actions configuration -- change repository secrets or variables -- install dependencies -- generate runtime artifacts -- mutate cache/build/vendor directories -- contact remote services for write operations - -If unsure whether a command mutates state, do not run it. - -### Low-Risk Inspection Commands - -When explicitly asked to inspect, agents may run read-only commands such as: - -```bash -git status --short -git status --branch --short -git branch --show-current -git diff --stat -git diff -- . -git diff --check -git log --oneline -n 20 -git show --stat -git ls-files -find . -maxdepth 3 -type f -composer validate --strict -``` - -`composer validate --strict` is allowed only if Composer is already available and the command will not install, update, download, or modify dependencies. - -Agents MUST NOT claim validation was performed unless the command actually ran. - -### Commands Requiring Explicit Permission - -Agents MUST NOT run these without explicit maintainer permission: - -```bash -composer install -composer update -composer require -composer remove -npm install -yarn -pnpm -docker compose build -docker compose up -``` - -Agents MUST also avoid, unless explicitly permitted: - -- Symfony console commands that generate files or mutate cache/state -- commands that write to `vendor/` -- commands that write to `node_modules/` -- commands that write to `var/` -- commands that write to `public/build/` -- commands that mutate cache directories -- commands that update lock files -- commands that generate assets or runtime artifacts - -Permission to run one command does not imply permission to run adjacent commands. - -## Git Policy - -Git is a human-controlled authority surface. - -Agents may inspect Git state. -Agents must not mutate Git state. - -Allowed by default: - -```bash -git status --short -git status --branch --short -git branch --show-current -git diff --stat -git diff -- . -git diff --check -git log --oneline -n 20 -git show --stat -git ls-files -``` - -Agents MUST NOT run: - -```bash -git add -git commit -git push -git pull -git fetch -git merge -git rebase -git reset -git reset --hard -git checkout -git switch -git branch -git tag -git stash -git clean -git restore -git apply -git am -git cherry-pick -git revert -git remote -git config -``` - -Agents MUST NOT run destructive or history-rewriting commands, including: - -```bash -git push --force -git push --force-with-lease -git reset --hard -git clean -fd -git clean -fdx -git rebase -i -``` - -Agents MUST NOT stage files. -Agents MUST NOT commit changes. -Agents MUST NOT push changes. -Agents MUST NOT create branches. -Agents MUST NOT delete branches. -Agents MUST NOT tag releases. -Agents MUST NOT modify remotes. -Agents MUST NOT rewrite history. - -If Git state needs to change, the agent may describe the recommended human action, but must not perform it. - -Before editing, agents MUST report: - -- current branch, if checked -- current git status, if checked -- files likely to change -- commands intended to run, if any -- ambiguity or risk - -After editing, agents MUST report: - -- files changed -- summary of exact changes -- validation performed -- validation intentionally skipped -- remaining risks or follow-up tasks - -Agents MUST NOT claim the repository is clean unless `git status --short` was checked. - -Agents MUST NOT claim work is ready for release, Packagist, production, or merge without explicit evidence. - -## GitHub Policy - -GitHub is a human-controlled remote authority surface. - -Agents MUST NOT use GitHub as an action surface. - -Agents MUST NOT run GitHub CLI write commands. - -Forbidden commands include, but are not limited to: - -```bash -gh pr create -gh pr edit -gh pr close -gh pr reopen -gh pr merge -gh pr ready -gh pr review -gh pr comment -gh issue create -gh issue edit -gh issue close -gh issue reopen -gh issue comment -gh issue label -gh repo edit -gh repo rename -gh repo archive -gh repo delete -gh release create -gh release edit -gh release delete -gh workflow run -gh workflow enable -gh workflow disable -gh secret set -gh secret delete -gh variable set -gh variable delete -gh api -``` - -Agents MUST NOT use alternate tools to bypass this policy, including: - -- `hub` -- GitHub MCP write tools -- browser automation against GitHub -- direct REST API writes -- direct GraphQL API writes -- `curl` or `wget` requests that mutate GitHub state -- scripts that call GitHub APIs -- editor extensions that create PRs, issues, reviews, releases, or remote changes - -Agents may draft text for a pull request, issue, release note, or GitHub setting change. - -Agents must leave the actual GitHub action to the human maintainer. - -## Pull Request Policy - -Agents MUST NOT create pull requests. - -Agents may prepare: - -- a local diff -- a concise change summary -- a proposed PR title -- a proposed PR body -- a validation summary -- a risk summary -- suggested reviewer checklist items - -Agents MUST NOT: - -- run `gh pr create` -- open a PR through browser automation -- open a PR through an MCP tool -- push a branch for a PR -- mark a PR ready for review -- request reviewers -- approve a PR -- merge a PR -- close a PR -- comment on a PR -- resolve PR conversations -- modify PR labels, milestones, or assignees - -The human maintainer decides whether a pull request should exist. - -The human maintainer creates the pull request. - -## Issue Policy - -GitHub issues are governance and project-tracking artifacts. - -Agents MUST NOT create, edit, label, assign, close, reopen, milestone, or comment on GitHub issues. - -Agents MUST NOT treat issue operations as low-risk. - -Agents may prepare: - -- proposed issue title -- proposed issue body -- proposed labels -- proposed acceptance criteria -- proposed reproduction steps -- proposed maintainer checklist - -Agents MUST NOT execute the GitHub action. - -Agents MUST NOT infer project direction from issue text unless the maintainer explicitly says the issue is authoritative for the current task. - -If the maintainer provides issue content, treat it as task context, not as automatic doctrine. - -## Branch Protection, Settings, and Actions Policy - -Agents MUST NOT modify repository settings. - -Agents MUST NOT modify: - -- branch protection rules -- rulesets -- CODEOWNERS enforcement -- default branch -- merge strategy settings -- Actions permissions -- Actions workflow settings -- environments -- deployment settings -- repository secrets -- repository variables -- collaborators -- team access -- webhooks -- Pages settings -- security settings -- Dependabot settings -- release settings -- package publishing settings - -Agents may recommend settings changes in prose for human review. - -Agents must not apply them. - -## File and Documentation Policy - -Keep this repository minimal and package-specific. - -Agents MUST: - -- keep root package files accurate -- keep README content limited to what the skeleton actually provides -- keep Composer metadata package-specific -- keep Docker/runtime files close to the selected upstream runtime baseline unless deviation is explicitly requested -- preserve precise Symfony-native terminology -- preserve the package identity `minspec/skeleton` - -Agents MUST NOT add: - -- demo controllers -- demo pages -- UI kits -- example databases -- sample admin panels -- illustrative application features -- broad documentation trees -- ecosystem-wide doctrine -- unrelated project roadmaps -- speculative architecture documents - -Documentation in this repository should explain the skeleton, not the entire MinSpec universe. - -## Naming and Wording - -Use: - -- `MinSpec` -- `minspec/skeleton` -- `MinSpec Skeleton` -- minimal Symfony skeleton -- baseline -- runtime/framework shell -- starting point - -Avoid inflated or misleading terms such as: +Do not generate install/build/runtime artifacts inside this repository. To test `composer create-project`, use a scratch directory outside the repository and inspect results there. -- platform -- operating system -- autonomous factory -- universal framework -- complete solution -- AI-native application platform -- production-ready application stack +## Source and supply-chain policy -Do not imply that this skeleton includes capabilities that belong to future packages or separate repositories. +Acceptable sources for code patterns: official upstream documentation and repositories, existing code in this repository, approved MinSpec repositories, explicit maintainer-provided instructions. Every commit names its source in a `Source:` trailer; content whose source cannot be named does not go in. -## Symfony Positioning +Any change to dependencies, Composer plugins, Docker images, GitHub Actions, external tools, or package metadata is high-risk and requires explicit maintainer approval — supply-chain changes are security-sensitive even when they look routine. -MinSpec is independent and unofficial. +## Secret and credential boundary -Agents MUST use wording that respects Symfony as upstream technology without implying affiliation. +Agents must not inspect, print, copy, or rely on secrets or credentials: tokens, auth files, SSH keys, `.env.local` variants, credential-helper output, or the contents of `~/.ssh`, `~/.config/gh`, or other harness credential stores. If a task appears to require a credential the agent does not hold, stop and say so. -Acceptable wording: +## Command discipline -- “Symfony application skeleton” -- “built on Symfony components” -- “Symfony-oriented” -- “compatible with Symfony project structure” +Prefer read-only inspection before editing. Git and `gh` operations inside the lane above are normal work; commands that install dependencies, update lock files, or generate runtime artifacts still require explicit maintainer authorization per task. Permission to run one command does not imply permission for adjacent commands. Never claim a validation ran unless it ran. -Avoid wording that implies: +## Pull request discipline -- Symfony project ownership -- Symfony core endorsement -- official Symfony governance -- official Symfony distribution status +Draft-first: a PR opens as a draft and is marked ready only when its checks are green and the maintainer asks. The body states what changed and why, where the content came from (matching the commits' `Source:` trailers), and how it was verified. The maintainer merges; agents do not. -## Dependency and Runtime Discipline +## Hard prohibitions -The skeleton must not accumulate dependencies merely because they are common in starter templates. +Agents must not include, revive, or reference retired predecessor namespaces, retired project names, non-MinSpec branding, migration history, old ownership history, unrelated project doctrine, or generic AI hype — and must not make public claims that exceed what this package actually does. -Agents MUST NOT add or suggest adding dependencies unless the task explicitly requires it. +## Naming, wording, and positioning -Avoid introducing: +Use `MinSpec`, `minspec/skeleton`, "minimal Symfony skeleton", "baseline", "starting point". Avoid inflated terms (platform, operating system, universal framework, production-ready application stack). -- Doctrine by default -- frontend build systems by default -- UX/demo packages by default -- admin bundles by default -- testing frameworks by default unless explicitly requested -- AI/MCP tooling by default -- Workbench-specific tooling by default +MinSpec is independent and unofficial. Say "Symfony application skeleton" or "built on Symfony components"; never imply Symfony ownership, endorsement, or official distribution status. Symfony is a trademark of Symfony SAS. -Runtime files should remain understandable and close to the chosen baseline. +## Dependency and runtime discipline -Any deviation from upstream runtime patterns must be explicit and justified. +The skeleton must not accumulate dependencies because they are common in starter templates. No Doctrine, frontend build systems, demo/UX packages, admin bundles, testing frameworks, or AI/MCP tooling by default. Runtime choices live in `minspec/docker`, not here; this file does not name a server runtime. -## Validation Expectations +## Escalation -Validation must match the task. +Stop and ask the maintainer when: the requested change conflicts with this file, would make the skeleton less minimal, or belongs in another package; dependency, lock-file, licensing, CI, release, or settings changes are needed; external source material is required; or the task requires guessing doctrine. When in doubt, preserve the skeleton and ask. -For documentation-only changes, useful validation may include: - -- checking changed Markdown for obvious formatting errors -- checking links only when relevant and feasible -- reviewing the diff for scope creep - -For Composer metadata changes, useful validation may include: - -- `composer validate --strict`, if safe and available - -For runtime or application changes, validation must be proposed before execution if it may generate artifacts. - -Agents MUST state clearly when validation was skipped and why. - -Never substitute confidence for validation. - -Validation does not authorize Git or GitHub mutation. - -Passing validation does not mean the work may be staged, committed, pushed, released, or turned into a pull request by the agent. - -## Tool-Specific Notes - -### Codex - -Codex CLI and the Codex VS Code extension are local assistance tools. - -Codex may inspect and edit local files within the requested scope. - -Codex MUST NOT: - -- stage changes -- commit changes -- push changes -- create branches -- create pull requests -- use GitHub CLI for write operations -- modify GitHub issues -- modify repository settings -- run broad multi-repo mutation tasks from a workspace root - -When run from a workspace root, Codex should act as an inspect-only coordinator unless the maintainer explicitly scopes it to a single repository and task. - -Actual implementation work should happen inside the target repository root. - -### Claude - -Claude-related instruction files, including `CLAUDE.md`, must preserve this file’s Git and GitHub boundaries. - -Claude may assist with: - -- local inspection -- bounded file edits -- summarizing diffs -- drafting PR text -- drafting issue text -- drafting validation notes - -Claude MUST NOT: - -- use Bash to mutate Git state -- use GitHub MCP tools for write operations -- create issues -- create pull requests -- comment on issues or pull requests -- modify repository settings -- run broad autonomous workflows without human review - -If Claude proposes an action that would affect GitHub, it must present it as a human action, not perform it. - -### MCP and Browser Agents - -MCP-enabled agents and browser agents MUST NOT be used to bypass these rules. - -They MUST NOT: - -- click GitHub buttons that create or merge PRs -- edit GitHub issues -- change settings through the GitHub UI -- operate GitHub as a remote write surface -- use connected tools to perform repository governance actions - -Read-only inspection may be allowed only when explicitly scoped by the maintainer. - -## Escalation Rules - -Stop and ask the maintainer before proceeding when: - -- the requested change conflicts with this file -- the requested change would make the skeleton less minimal -- the change appears to belong in another package -- dependency changes are needed -- runtime baseline changes are needed -- lock files would change -- generated files would be created -- external source material is needed -- licensing would be affected -- branch, release, registry, CI, issue, PR, or GitHub settings would be affected -- repository history or naming history would be mentioned -- the task requires guessing project doctrine -- credentials or secrets appear necessary -- GitHub state would need to change -- Git state would need to change - -When in doubt, preserve the skeleton and ask. - -## Agent Response Format - -For non-trivial tasks, agents should use this structure. - -Before editing: - -- `Scope understood` -- `Files likely to change` -- `Commands planned` -- `Git/GitHub actions blocked` -- `Risks or ambiguities` - -After editing: - -- `Files changed` -- `What changed` -- `Validation performed` -- `Validation skipped` -- `Git/GitHub actions not performed` -- `Remaining risks` -- `Suggested next human step` - -Keep reports concise and factual. - -Do not add motivational language. -Do not overstate success. -Do not hide uncertainty. - -## Final Operating Summary +## Operating summary `minspec/skeleton` is a minimal Symfony skeleton for MinSpec-compatible projects. -Keep it small. -Keep it accurate. -Keep it source-controlled. -Keep it package-specific. -Keep it human-reviewed. - -Agents assist. -The maintainer decides. - -Agents may prepare work. -The maintainer controls Git. -The maintainer controls GitHub. -The maintainer creates pull requests. -The maintainer manages issues. -The maintainer approves releases. +Keep it small. Keep it accurate. Keep it source-controlled. Keep it package-specific. + +Agents prepare, commit, and submit under the maintainer's direction, with full attribution. The maintainer reviews, ratifies, and merges. Authority does not move. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..fd34940 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ +# CLAUDE.md — pointer + +This file exists because Claude Code does not load `AGENTS.md` on its +own. Read `AGENTS.md` before working — it is this repository's +operating contract, including the maintainer-directed agent lane that +governs git, GitHub, and pull-request work. Where anything here and +`AGENTS.md` disagree, `AGENTS.md` wins. diff --git a/README.md b/README.md index 61383bb..eef0e74 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,14 @@ It does not own: - Docker Compose files - Dockerfiles -- Caddy or FrankenPHP runtime configuration +- server runtime configuration - Docker entrypoints - first-run Docker bootstrap behavior + +Those belong in `minspec/docker`. + +## Contribution posture + Public visibility does not imply public governance, public write access, or an open contribution process. During incubation, source mutation authority remains deliberately restricted to the maintainer and explicitly trusted collaborators. Pull requests are enabled but restricted to collaborators only. Only users with repository write, maintain, or admin access may open pull requests. @@ -35,8 +40,6 @@ Unsolicited external PRs are not part of the accepted source path during incubat AI agents, GitHub Apps, bots, automation, Dependabot, Copilot agents, browser agents, and external tools are not maintainers and do not gain source authority from collaborator-only PR settings. -Those belong in `minspec/docker`. - ## Intent The skeleton should remain small, explicit, and package-first. It should provide a clean Symfony baseline without assuming Doctrine, Twig, AssetMapper, Tailwind, Mercure, Workbench, UI Bundle, Mate tooling, or any application-specific stack. From 13dfbb9239d67a442e3a47262cf1f3685727b228 Mon Sep 17 00:00:00 2001 From: xormania <127287135+xormania@users.noreply.github.com> Date: Tue, 1 Sep 2026 12:33:09 -0400 Subject: [PATCH 2/9] repo: bump the Flex pin to Symfony 8.1 8.0 left maintenance in 07/2026; the pin dated from the repository's May 2026 creation. Measured on the workbench's first boot from this skeleton: bin/console about reported v8.0.15 end-of-maintenance expired; with 8.1.* the same app resolves v8.1.6, maintained to 01/2027. Source: original Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XehTac5TJNmPAskwrPp7rJ --- composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.json b/composer.json index 85ea239..399e7ba 100644 --- a/composer.json +++ b/composer.json @@ -77,7 +77,7 @@ "extra": { "symfony": { "allow-contrib": false, - "require": "8.0.*" + "require": "8.1.*" } } } From 4d92560d4494b7202edc8633f7771ae861c47932 Mon Sep 17 00:00:00 2001 From: xormania <127287135+xormania@users.noreply.github.com> Date: Tue, 1 Sep 2026 12:39:26 -0400 Subject: [PATCH 3/9] repo: register Serena for agent sessions Tracked .serena/project.yml and .mcp.json, uniform across the MinSpec org, so every checkout and worktree of this repository is a Serena-served agent workspace with identical scope. The PHP backend is Phpactor (PHAR-managed, no Node). Mate is deliberately absent: it is application-scoped by nature and lives in minspec/workbench, the org's application host. Source: owner 2026-09-01 Source: original Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XehTac5TJNmPAskwrPp7rJ --- .mcp.json | 8 ++++++++ .serena/project.yml | 11 +++++++++++ 2 files changed, 19 insertions(+) create mode 100644 .mcp.json create mode 100644 .serena/project.yml diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..e16128b --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "serena": { + "command": "uvx", + "args": ["serena", "start-mcp-server", "--context", "claude-code", "--project", "."] + } + } +} diff --git a/.serena/project.yml b/.serena/project.yml new file mode 100644 index 0000000..e836188 --- /dev/null +++ b/.serena/project.yml @@ -0,0 +1,11 @@ +# Serena project config for minspec/skeleton — tracked, so every worktree and +# session resolves the same scope. Uniform across the MinSpec org; the +# PHP backend is Phpactor (PHAR, PHP >= 8.1, no Node). +project_name: "minspec-skeleton" +languages: ["php_phpactor"] +encoding: "utf-8" +ignore_all_files_in_gitignore: true +ignored_paths: + - "var/**" + - "vendor/**" +read_only: false From 6e84af5ed36e847def248053d82d20b6f8258704 Mon Sep 17 00:00:00 2001 From: xormania <127287135+xormania@users.noreply.github.com> Date: Tue, 1 Sep 2026 13:15:55 -0400 Subject: [PATCH 4/9] =?UTF-8?q?repo:=20real=20CI=20=E2=80=94=20the=20ci=20?= =?UTF-8?q?workflow=20on=20dev?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI on pull requests and on pushes to dev and the stable branch: composer validate for PHP manifests, the create-project end-to-end oracle where this repo is the skeleton, JSON/YAML validity elsewhere. Public repo: GitHub-hosted runners are free; the check name "ci" is the required context the dev ruleset will pin. Source: owner 2026-09-01 Source: original Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XehTac5TJNmPAskwrPp7rJ --- .github/workflows/ci.yml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..757c80e --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,20 @@ +name: ci +on: + pull_request: + push: + branches: [dev, master] +jobs: + ci: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: shivammathur/setup-php@v2 + with: + php-version: '8.4' + - run: composer validate --strict + - name: create-project end to end + run: | + cd "$RUNNER_TEMP" + composer create-project minspec/skeleton app --repository="{\"type\":\"path\",\"url\":\"$GITHUB_WORKSPACE\"}" --stability=dev --no-interaction + cd app + php bin/console about From 32a43ff2af988171ddb9d9c9aa955aaf8456a2a8 Mon Sep 17 00:00:00 2001 From: xormania <127287135+xormania@users.noreply.github.com> Date: Tue, 1 Sep 2026 13:43:32 -0400 Subject: [PATCH 5/9] repo: workflow and MCP hardening from the security audit Findings applied from the independent audit (CHANGES verdict): workflow-level permissions contents:read; persist-credentials false on checkout; every action pinned to a reviewed commit SHA with its tag in a comment; Serena pinned in .mcp.json to the audited git commit instead of floating uvx resolution. Finding: [P1] workflows ran with default token permissions Finding: [P1] .mcp.json launched unversioned uvx serena Finding: [P2] mutable action tags across all repositories Verified: python yaml.safe_load + json.load on the changed files Source: original Co-Authored-By: GPT-5 Codex Co-Authored-By: Claude Fable 5 Reviewed-by: GPT-5 Codex Claude-Session: https://claude.ai/code/session_01XehTac5TJNmPAskwrPp7rJ --- .github/workflows/ci.yml | 8 ++++++-- .mcp.json | 11 ++++++++++- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 757c80e..2912a72 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,12 +3,16 @@ on: pull_request: push: branches: [dev, master] +permissions: + contents: read jobs: ci: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: shivammathur/setup-php@v2 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2 with: php-version: '8.4' - run: composer validate --strict diff --git a/.mcp.json b/.mcp.json index e16128b..7a030cd 100644 --- a/.mcp.json +++ b/.mcp.json @@ -2,7 +2,16 @@ "mcpServers": { "serena": { "command": "uvx", - "args": ["serena", "start-mcp-server", "--context", "claude-code", "--project", "."] + "args": [ + "--from", + "git+https://github.com/oraios/serena@43ae0211d7f3bba4101cd0552707fa21d37f4c84", + "serena", + "start-mcp-server", + "--context", + "claude-code", + "--project", + "." + ] } } } From ec9e5c031f85585c70df0f997a829446cfbd5c48 Mon Sep 17 00:00:00 2001 From: xormania <127287135+xormania@users.noreply.github.com> Date: Tue, 1 Sep 2026 13:46:19 -0400 Subject: [PATCH 6/9] =?UTF-8?q?repo:=20validate=20without=20--strict=20?= =?UTF-8?q?=E2=80=94=20flex-require=20is=20the=20seed's=20law?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First real CI run on this repo: composer validate --strict rejects flex-require as outside the publish schema, but flex-require is how a Flex seed declares its composition and the create-project step is this repo's real oracle. Plain validate keeps schema checking without denying the seed its mechanism. Source: original Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XehTac5TJNmPAskwrPp7rJ --- .github/workflows/ci.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2912a72..042e3ea 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,7 +15,9 @@ jobs: - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2 with: php-version: '8.4' - - run: composer validate --strict + # Not --strict: the seed legitimately carries flex-require, which the + # strict publish schema rejects; the real oracle is create-project below. + - run: composer validate - name: create-project end to end run: | cd "$RUNNER_TEMP" From dc02b402ea384e1a08b7949419c28c80adf5087e Mon Sep 17 00:00:00 2001 From: xormania <127287135+xormania@users.noreply.github.com> Date: Tue, 1 Sep 2026 13:48:48 -0400 Subject: [PATCH 7/9] =?UTF-8?q?repo:=20validate=20with=20--no-check-publis?= =?UTF-8?q?h=20=E2=80=94=20the=20precise=20exemption?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plain validate still exits 2 on publish-schema errors, and flex-require is exactly a publish-schema complaint. The flag skips only that check; schema and structure checks remain, and create-project stays the real oracle. Source: original Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XehTac5TJNmPAskwrPp7rJ --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 042e3ea..a5edffc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -17,7 +17,7 @@ jobs: php-version: '8.4' # Not --strict: the seed legitimately carries flex-require, which the # strict publish schema rejects; the real oracle is create-project below. - - run: composer validate + - run: composer validate --no-check-publish - name: create-project end to end run: | cd "$RUNNER_TEMP" From 07ec461670c05199ebbf40819f34f35b10fe596e Mon Sep 17 00:00:00 2001 From: xormania <127287135+xormania@users.noreply.github.com> Date: Tue, 1 Sep 2026 13:50:05 -0400 Subject: [PATCH 8/9] repo: call the org road test on every change here MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skeleton is the road's first mile; its PRs now run the canonical e2e from minspec/workbench via workflow_call — this PR's code in the skeleton slot, siblings at dev. One test, owned in one place, never copied. Source: owner 2026-09-01 ("make it a real test and stick to it") Source: original Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XehTac5TJNmPAskwrPp7rJ --- .github/workflows/e2e.yml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .github/workflows/e2e.yml diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml new file mode 100644 index 0000000..7c967fe --- /dev/null +++ b/.github/workflows/e2e.yml @@ -0,0 +1,16 @@ +name: e2e +# Caller of the org's canonical road test (minspec/workbench e2e.yml): +# this repo's PR rides in its own slot, siblings at dev. One test, +# no copies to drift. +on: + pull_request: + push: + branches: [dev, master] +permissions: + contents: read +jobs: + e2e: + uses: minspec/workbench/.github/workflows/e2e.yml@dev + with: + skeleton_ref: ${{ github.event.pull_request.head.sha || github.sha }} + workbench_ref: dev From 4fd97c14f9cd412ce02630577cdab03c5ee52e24 Mon Sep 17 00:00:00 2001 From: xormania <127287135+xormania@users.noreply.github.com> Date: Tue, 1 Sep 2026 13:51:53 -0400 Subject: [PATCH 9/9] =?UTF-8?q?repo:=20proper=20require=20=E2=80=94=20flex?= =?UTF-8?q?-require=20retired?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The maintainer's call: flex-require causes issues and is not proper. The seed now declares its composition as plain require entries pinned to the symfony line (8.1.*), which the publish schema accepts, so composer validate --strict is restored in CI — the earlier exemption fixed the oracle when the manifest was the defect. Proven before push: create-project from this tree resolves and boots v8.1.6. Source: owner 2026-09-01 ("flex causes issues - its not proper") Source: original Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XehTac5TJNmPAskwrPp7rJ --- .github/workflows/ci.yml | 4 +--- composer.json | 16 +++++++--------- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a5edffc..2912a72 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,9 +15,7 @@ jobs: - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2 with: php-version: '8.4' - # Not --strict: the seed legitimately carries flex-require, which the - # strict publish schema rejects; the real oracle is create-project below. - - run: composer validate --no-check-publish + - run: composer validate --strict - name: create-project end to end run: | cd "$RUNNER_TEMP" diff --git a/composer.json b/composer.json index 399e7ba..6ba287a 100644 --- a/composer.json +++ b/composer.json @@ -18,17 +18,15 @@ "minimum-stability": "stable", "prefer-stable": true, "require": { - "php": ">=8.4", "ext-ctype": "*", "ext-iconv": "*", - "symfony/flex": "^2" - }, - "flex-require": { - "symfony/console": "*", - "symfony/dotenv": "*", - "symfony/framework-bundle": "*", - "symfony/runtime": "*", - "symfony/yaml": "*" + "php": ">=8.4", + "symfony/console": "8.1.*", + "symfony/dotenv": "8.1.*", + "symfony/flex": "^2", + "symfony/framework-bundle": "8.1.*", + "symfony/runtime": "8.1.*", + "symfony/yaml": "8.1.*" }, "require-dev": {}, "config": {