Agent Workflow Dotfiles
junpakPark/agent-workflow-dotfiles
Skills agnósticas e bootstrap PLAN_ROOT para workflows de agentes Claude/Codex
Ver no GitHubRepositório de skills neutros para Claude e Codex, com protocolo compartilhado sincronizado e ferramentas de bootstrap para novos projetos. Gerencia dotfiles de planejamento e execução via symlinks ou cópia, incluindo validação de sincronização de protocolo.
Instalação
npx convez-ai junpakPark/agent-workflow-dotfiles1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Configurar ambiente de trabalho compartilhado entre Claude e Codex
- Bootstrapping automático de estrutura de planejamento em novos projetos
- Sincronizar e validar protocol bundles entre múltiplos agentes
Veredito

Ferramenta infraestrutural de nicho para equipes que orquestram workflows entre Claude e Codex em escala. Requer compreensão de dotfiles, symlinks e convenções de protocolo. Valor alto para pipelines de agentes estabelecidos, baixa relevância para usuários ocasionais.
README
A tradução para o português deste README ainda está na fila.
Agent Workflow Dotfiles
한국어: README.ko.md
This repo manages project-neutral agent workflow assets:
- Claude and Codex skills in dotfiles form.
- A shared protocol reference that must stay byte-identical across both ecosystems.
- A reusable PLAN_ROOT skeleton for bootstrapping new projects.
Project Neutrality Rule
Git-managed files in this repo must stay project-neutral. Do not commit specific project names, customer names, absolute local repo paths, runtime artifact identifiers, auth files, logs, history files, local databases, caches, plugin caches, or project-specific plan/ artifacts. Acceptable placeholders are <repo-root>, <project-root>, and ${HOME}.
Repo Structure
claude/skills/- Claude planning and intent-review skills.codex/skills/- Codex execution, review, quality, and finalization skills.templates/plan-root/- empty PLAN_ROOT skeleton and genericLEGACY_PATH_MAP.md.scripts/install-skills.sh- installs skills to Claude and Codex homes.scripts/bootstrap-plan-root.sh- createsplan/skeleton in a target project.scripts/check-protocol-sync.sh- validates the Claude/Codex protocol bundle mirrors and manual child-checkpoint handoff regression guards.
Prerequisites
- Claude home is
${HOME}/.claude. - Codex home is
${HOME}/.codex. - Symlink install is the default.
- If an installed target skill path already exists as a real directory, the install script stops instead of overwriting it.
- If an installed target skill path is already a symlink, the install script may replace that symlink.
First Install Runbook
- Clone this repo by your standard Git remote into
<repo-root>if needed, then confirm and enter it:
test -d "<repo-root>/.git"
cd "<repo-root>"
- Verify protocol sync:
scripts/check-protocol-sync.sh
- Preview skill installation:
scripts/install-skills.sh --dry-run
- Install skills with symlinks:
scripts/install-skills.sh
- Confirm installed targets:
ls -la "${HOME}/.claude/skills"
ls -la "${HOME}/.codex/skills"
Copy Install
Use copy mode only when symlinks are not appropriate for the machine:
cd "<repo-root>"
scripts/install-skills.sh --copy
Symlink mode reflects future repo changes immediately after git pull. Copy mode creates independent directories under ${HOME}/.claude/skills and ${HOME}/.codex/skills; after git pull, move stale copied skill directories aside and rerun scripts/install-skills.sh --copy.
Bootstrap A Project PLAN_ROOT
Run this from the dotfiles repo:
cd "<repo-root>"
scripts/bootstrap-plan-root.sh "<project-root>"
The script creates:
<project-root>/plan/families<project-root>/plan/check<project-root>/plan/archive<project-root>/plan/roadmap<project-root>/plan/manual<project-root>/plan/LEGACY_PATH_MAP.md
Each empty directory receives .gitkeep. Existing files are not overwritten. If <project-root>/.gitignore does not contain plan/, the script appends it. If <project-root>/.gitignore does not exist, the script creates it with plan/.
The bootstrap script stops instead of creating canonical plan/ if any
legacy docs-based plan root exists:
<project-root>/docs/plan<project-root>/docs/check<project-root>/docs/archive<project-root>/docs/roadmap<project-root>/docs/runbook
Migration or artifact moves require explicit user approval outside this script.
PLAN_ROOT Preflight In Skills
Each plan-*, exec-*, and finalize-* stage skill must apply the
PLAN_ROOT preflight before reading or writing plan artifacts:
- If canonical
plan/is absent, report that bootstrap is required. - If
docs/plan,docs/check,docs/archive,docs/roadmap, ordocs/runbookexists, stop and report the legacy conflict. - If only some canonical directories are missing and no legacy conflict exists, create the missing directories idempotently.
- Never overwrite existing files.
- Never migrate or move artifacts without explicit user approval.
Update Procedure
For symlink installs:
cd "<repo-root>"
git pull
scripts/check-protocol-sync.sh
For copy installs:
cd "<repo-root>"
git pull
scripts/check-protocol-sync.sh
scripts/install-skills.sh --copy
If copy install stops because a target is a real directory, move that target aside first and rerun the copy install.
Validation
Run these checks from <repo-root>:
scripts/check-protocol-sync.sh
bash -n scripts/install-skills.sh
bash -n scripts/bootstrap-plan-root.sh
bash -n scripts/check-protocol-sync.sh
find . -type f | sort
Check for project-specific strings by setting the terms for the project being audited:
PROJECT_TERMS='project-name|customer-name|domain-name|absolute-local-repo-path|runtime-artifact-name'
rg -n "${PROJECT_TERMS}" .
Run Codex skill validation when the local system validator exists:
for skill in \
plan-protocol \
exec-run \
exec-draft \
draft-review \
exec-tests \
test-review \
exec-impl \
exec-code-quality \
finalize-run \
finalize-closeout \
finalize-archive \
plan-review-worker \
code-quality-worker
do
python "${HOME}/.codex/skills/.system/skill-creator/scripts/quick_validate.py" "codex/skills/${skill}"
done
Validate a target project after bootstrap:
test -d "<project-root>/plan/families"
test -d "<project-root>/plan/check"
test -d "<project-root>/plan/archive"
test -d "<project-root>/plan/roadmap"
test -d "<project-root>/plan/manual"
test -f "<project-root>/plan/LEGACY_PATH_MAP.md"
grep -qxF "plan/" "<project-root>/.gitignore"
Troubleshooting
Existing target skill is a real directory: Move it aside or inspect it manually. The install script will not overwrite non-symlink skill directories.
Protocol sync mismatch:
Keep the mirrored protocol bundle byte-identical across Claude and Codex: plan-protocol.md, probes.md, and the checkpoint schema files under references/schemas/. The sync check also fails on manual child-checkpoint handoff regressions, including stale bare-stdout wording, missing manual handoff invariant phrases, active claude -p / --json-schema checkpoint invocation text, failed-2 debug artifact wording, or top-level $schema in checkpoint schemas. Fix the reported file or phrase, copy the exact final bytes to the matching mirror when applicable, then rerun scripts/check-protocol-sync.sh.
Target project has no .gitignore:
scripts/bootstrap-plan-root.sh creates <project-root>/.gitignore with plan/.
Copy install has stale skills:
Move stale copied skill directories out of ${HOME}/.claude/skills or ${HOME}/.codex/skills, then rerun scripts/install-skills.sh --copy.
Security And Privacy
Do not commit:
.systemskills.- Claude or Codex auth files.
- Logs, history, sessions, cache, or local database files.
- Plugin cache or runtime generated files.
- Project-specific
plan/artifacts. - Customer, domain, or machine-specific identifiers.