{"id":50601323,"url":"https://github.com/phdigital01/structural-frame-protocol","last_synced_at":"2026-06-05T19:00:13.867Z","repository":{"id":362669014,"uuid":"1260229431","full_name":"phdigital01/structural-frame-protocol","owner":"phdigital01","description":"A cross-agent construction standard for building secure, consistent AI-assisted software.","archived":false,"fork":false,"pushed_at":"2026-06-05T12:13:44.000Z","size":2015,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T12:27:40.464Z","etag":null,"topics":["ai-agents","coding-agents","design-system","documentation","hermes-skill","software-engineering"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phdigital01.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T09:23:49.000Z","updated_at":"2026-06-05T12:13:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phdigital01/structural-frame-protocol","commit_stats":null,"previous_names":["phdigital01/structural-frame-protocol"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/phdigital01/structural-frame-protocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phdigital01%2Fstructural-frame-protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phdigital01%2Fstructural-frame-protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phdigital01%2Fstructural-frame-protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phdigital01%2Fstructural-frame-protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phdigital01","download_url":"https://codeload.github.com/phdigital01/structural-frame-protocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phdigital01%2Fstructural-frame-protocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33955543,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","coding-agents","design-system","documentation","hermes-skill","software-engineering"],"created_at":"2026-06-05T19:00:12.825Z","updated_at":"2026-06-05T19:00:13.848Z","avatar_url":"https://github.com/phdigital01.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Structural Frame Protocol\n\n![Structural Frame Protocol cover](skills/structural-frame-protocol/assets/structural-frame-protocol-cover.jpg)\n\nA cross-agent construction standard for building secure, consistent AI-assisted software.\n\n\u003e **Agents change. The frame holds.**\n\u003e **AI accelerates construction. It must not accelerate improvisation.**\n\nThis repository contains a reusable AI-agent skill and supporting templates for teams that want consistent software delivery across Claude, Codex, Kimi, DeepSeek, Gemini, local agents, Hermes, and future models.\n\n## Why this exists\n\nAI agents are fast, but without a structural frame they improvise:\n\n- they start coding before understanding the terrain;\n- they keep plans only in chat;\n- they build UI before data/auth/contracts;\n- they add security as a final checklist instead of a load-bearing requirement;\n- they invent architecture, component patterns, dependencies, and visual systems;\n- they create inconsistent design from screen to screen;\n- they lose project state between sessions;\n- they declare work done without inspection.\n\nStructural Frame Protocol turns that into a disciplined workflow. The executable rules and phase gates live in [SKILL.md](skills/structural-frame-protocol/SKILL.md); this README is the human entrypoint.\n\n## Intensity modes\n\nUse the lightest mode that still protects the project:\n\n- **Lite** for tiny safe edits, copy, isolated docs cleanup, and low-risk presentation changes.\n- **Standard** for normal features, modules, refactors, UI workflows, and API changes.\n- **Critical** for auth, permissions, production, migrations, billing, sensitive data, paid providers, destructive operations, broad shared contracts, or multi-agent work.\n- **Tier 3/chat-only** for constrained agents that can only produce checklists, plans, and handoffs.\n\nLite work should not create heavy documentation. Critical work requires security/risk/rollback thinking and stronger verification.\n\n## Operating rules\n\nThe canonical wording is in [SKILL.md](skills/structural-frame-protocol/SKILL.md). The short version:\n\n- Security is load-bearing.\n- No new material without approval.\n- Only current work can promote executable work.\n\nRoadmaps, audits, references, archived plans, proposed plans, and future ideas are context. They are not executable until promoted through `docs/work/current.md` or the project's explicit equivalent.\n\n## Repository layout\n\n```txt\n.\n├── skills/structural-frame-protocol/   # runtime skill package\n├── examples/                           # repo-only walkthroughs\n├── evals/                              # repo-only behavior checks\n├── scripts/                            # repo maintenance scripts\n└── .github/workflows/validate.yml      # repo CI\n```\n\n## Quick start for agents\n\n1. Read project-local instructions: `AGENTS.md`, `.hermes/context.md`, `docs/START_HERE.md`, or equivalent.\n2. Read `docs/work/current.md` or identify the project's current-work equivalent.\n3. Decide Lite, Standard, Critical, or Tier 3/chat-only mode.\n4. Map existing documentation to protocol roles before creating new files.\n5. Define the security model before implementation when users/data/production are involved.\n6. Define material standards and the surface-specific design authority before UI/code generation.\n7. Write or promote a persistent plan for non-trivial work.\n8. Execute one stage at a time.\n9. Inspect before advancing.\n10. Update current-work, status, TODO, plan, and handoff docs.\n\n## Quick start for teams\n\nFor a new or under-documented project, bootstrap the documentation foundation with one command:\n\n```bash\npython skills/structural-frame-protocol/scripts/init_project.py path/to/your-project\n```\n\nAdd `--production` to also install rollback, incident-response, release-signoff, and dependency-policy docs:\n\n```bash\npython skills/structural-frame-protocol/scripts/init_project.py path/to/your-project --production\n```\n\nThis creates the `docs/` tree and materializes the opinionated base — reading order, directory roles, security model, and the current-work entrypoint — from the templates, stamped with today's date. It never overwrites existing files, so it is safe to re-run.\n\nThen fill the `[placeholders]` and adapt to your repo. Do not create heavy documentation blindly in mature projects; map to the project's existing docs first.\n\n## Documentation lifecycle\n\nRecommended flow:\n\n```txt\nevolution idea -\u003e proposed plan -\u003e current-work promotion -\u003e active plan -\u003e stage execution -\u003e inspection -\u003e archive/reference/ADR\n```\n\nSee:\n\n- `skills/structural-frame-protocol/references/documentation-information-architecture.md`\n- `skills/structural-frame-protocol/templates/current-work.md`\n- `skills/structural-frame-protocol/templates/evolution-idea.md`\n- `skills/structural-frame-protocol/references/verification-tiers.md`\n- `skills/structural-frame-protocol/references/surface-design-authority.md`\n\n## Examples and evals\n\n- `examples/new-project/` — documentation foundation for a new project.\n- `examples/handoff/` — brownfield multi-agent handoff showing a blocked material divergence.\n- `examples/walkthrough-lite-copy-fix/` — Lite flow from request to narrow verification.\n- `examples/walkthrough-standard-feature/` — Standard flow from request to current-work, plan, inspection, and handoff.\n- `examples/walkthrough-critical-auth/` — Critical auth/security flow with risk, rollback, and release sign-off.\n- `evals/` — zero-cost prompts and rubric for checking whether agents consume the protocol safely.\n\nRun a local response check with:\n\n```bash\npython3 scripts/evaluate_agent_response.py --case critical-auth --response path/to/agent-response.md\n```\n\n## Installation\n\n### Recommended global skill install\n\nInstall Structural Frame Protocol as a global skill, not as a Claude plugin. The repository exposes the runtime package under `skills/structural-frame-protocol/`, so the skills.sh CLI installs only that skill folder instead of the repo root:\n\n```bash\nnpx skills add phdigital01/structural-frame-protocol -g --copy\n```\n\nTarget specific agents when needed:\n\n```bash\nnpx skills add phdigital01/structural-frame-protocol -g --copy --agent claude-code codex opencode\n```\n\nThe repository intentionally does not ship a Claude Code plugin marketplace adapter. A global skill avoids duplicate loading paths, extra generated bundles, and plugin-specific maintenance.\n\n### Clean install from a checkout\n\nFor local development or Windows setups where you want a clean runtime-only skill folder, use the installer script instead of copying the whole repository:\n\n```bash\npython3 scripts/install_global_skill.py --target ~/.agents/skills/structural-frame-protocol\n```\n\nPowerShell:\n\n```powershell\npy scripts\\install_global_skill.py --target \"$env:USERPROFILE\\.agents\\skills\\structural-frame-protocol\"\n```\n\nThe installer copies only runtime skill material from `skills/structural-frame-protocol/`: `SKILL.md`, `docs/`, `references/`, `templates/`, `assets/`, and runtime scripts. It excludes repo-development assets such as `.git/`, `.github/`, `evals/`, `examples/`, `node_modules/`, generated packages, and plugin artifacts.\n\nIf Claude Code should read the same installed skill, point its skill directory at the global copy with a symlink or junction instead of installing a second copy. On Windows:\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.claude\\skills\" | Out-Null\nNew-Item -ItemType Junction `\n  -Path \"$env:USERPROFILE\\.claude\\skills\\structural-frame-protocol\" `\n  -Target \"$env:USERPROFILE\\.agents\\skills\\structural-frame-protocol\"\n```\n\n### Hermes Agent\n\nThis repository remains Hermes-compatible. The expected skill entry point is:\n\n```txt\nskills/structural-frame-protocol/SKILL.md\n```\n\nFor local Hermes profile sync, prefer the runtime installer pointed at the profile skill directory instead of a full-repo copy.\n\n### Native skill agents\n\nUse the runtime skill shape when the platform supports `SKILL.md` plus linked files:\n\n```txt\nstructural-frame-protocol/\n├── SKILL.md\n├── references/\n├── templates/\n├── docs/\n├── assets/\n└── scripts/\n```\n\nThe skill folder name must match the `name` in `SKILL.md` (`structural-frame-protocol`).\n\n### Repository-instruction agents\n\nFor agents that read project instruction files instead of native skills, reference the protocol from `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or the platform equivalent. Do not paste divergent copies of the full protocol into every repo.\n\nSee:\n\n- `skills/structural-frame-protocol/docs/07-agent-platform-compatibility.md`\n- `skills/structural-frame-protocol/templates/platform-adapter.md`\n\n## Publication roadmap\n\nThe GitHub repository is the source of truth. The runtime distribution surface is `skills/structural-frame-protocol/`; repo-only files are maintenance, examples, evals, CI, and governance.\n\nCurrent channels and adapters:\n\n- Global skill install through `npx skills add phdigital01/structural-frame-protocol -g --copy`.\n- Hermes Skills Hub / local Hermes skill folders.\n- Agent Skills format conformance (the standard `SKILL.md` shape), which keeps the skill portable across compatible clients.\n- Third-party skill directories (ClawHub, GitHub registries) via `hermes skills publish`, pending acceptance.\n- Repo-instruction adapters for Codex, Copilot, Cursor, Windsurf, Gemini CLI, Cline, Roo, and similar agents.\n\nSee `skills/structural-frame-protocol/docs/08-skill-library-publication.md` for gates, packaging rules, smoke tests, and registry records.\n\n## Validation\n\n```bash\npython3 scripts/validate.py\npython3 scripts/smoke_init.py\npython3 scripts/install_global_skill.py --dry-run --target /tmp/skills/structural-frame-protocol\n```\n\nCI runs the same validation on pull requests.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphdigital01%2Fstructural-frame-protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphdigital01%2Fstructural-frame-protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphdigital01%2Fstructural-frame-protocol/lists"}