https://github.com/phdigital01/structural-frame-protocol
A cross-agent construction standard for building secure, consistent AI-assisted software.
https://github.com/phdigital01/structural-frame-protocol
ai-agents coding-agents design-system documentation hermes-skill software-engineering
Last synced: 16 days ago
JSON representation
A cross-agent construction standard for building secure, consistent AI-assisted software.
- Host: GitHub
- URL: https://github.com/phdigital01/structural-frame-protocol
- Owner: phdigital01
- License: mit
- Created: 2026-06-05T09:23:49.000Z (16 days ago)
- Default Branch: main
- Last Pushed: 2026-06-05T12:13:44.000Z (16 days ago)
- Last Synced: 2026-06-05T12:27:40.464Z (16 days ago)
- Topics: ai-agents, coding-agents, design-system, documentation, hermes-skill, software-engineering
- Language: Python
- Size: 1.92 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Governance: GOVERNANCE.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# Structural Frame Protocol
A cross-agent construction standard for building secure, consistent AI-assisted software.
> **Agents change. The frame holds.**
> **AI accelerates construction. It must not accelerate improvisation.**
This 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.
## Why this exists
AI agents are fast, but without a structural frame they improvise:
- they start coding before understanding the terrain;
- they keep plans only in chat;
- they build UI before data/auth/contracts;
- they add security as a final checklist instead of a load-bearing requirement;
- they invent architecture, component patterns, dependencies, and visual systems;
- they create inconsistent design from screen to screen;
- they lose project state between sessions;
- they declare work done without inspection.
Structural 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.
## Intensity modes
Use the lightest mode that still protects the project:
- **Lite** for tiny safe edits, copy, isolated docs cleanup, and low-risk presentation changes.
- **Standard** for normal features, modules, refactors, UI workflows, and API changes.
- **Critical** for auth, permissions, production, migrations, billing, sensitive data, paid providers, destructive operations, broad shared contracts, or multi-agent work.
- **Tier 3/chat-only** for constrained agents that can only produce checklists, plans, and handoffs.
Lite work should not create heavy documentation. Critical work requires security/risk/rollback thinking and stronger verification.
## Operating rules
The canonical wording is in [SKILL.md](skills/structural-frame-protocol/SKILL.md). The short version:
- Security is load-bearing.
- No new material without approval.
- Only current work can promote executable work.
Roadmaps, 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.
## Repository layout
```txt
.
├── skills/structural-frame-protocol/ # runtime skill package
├── examples/ # repo-only walkthroughs
├── evals/ # repo-only behavior checks
├── scripts/ # repo maintenance scripts
└── .github/workflows/validate.yml # repo CI
```
## Quick start for agents
1. Read project-local instructions: `AGENTS.md`, `.hermes/context.md`, `docs/START_HERE.md`, or equivalent.
2. Read `docs/work/current.md` or identify the project's current-work equivalent.
3. Decide Lite, Standard, Critical, or Tier 3/chat-only mode.
4. Map existing documentation to protocol roles before creating new files.
5. Define the security model before implementation when users/data/production are involved.
6. Define material standards and the surface-specific design authority before UI/code generation.
7. Write or promote a persistent plan for non-trivial work.
8. Execute one stage at a time.
9. Inspect before advancing.
10. Update current-work, status, TODO, plan, and handoff docs.
## Quick start for teams
For a new or under-documented project, bootstrap the documentation foundation with one command:
```bash
python skills/structural-frame-protocol/scripts/init_project.py path/to/your-project
```
Add `--production` to also install rollback, incident-response, release-signoff, and dependency-policy docs:
```bash
python skills/structural-frame-protocol/scripts/init_project.py path/to/your-project --production
```
This 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.
Then 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.
## Documentation lifecycle
Recommended flow:
```txt
evolution idea -> proposed plan -> current-work promotion -> active plan -> stage execution -> inspection -> archive/reference/ADR
```
See:
- `skills/structural-frame-protocol/references/documentation-information-architecture.md`
- `skills/structural-frame-protocol/templates/current-work.md`
- `skills/structural-frame-protocol/templates/evolution-idea.md`
- `skills/structural-frame-protocol/references/verification-tiers.md`
- `skills/structural-frame-protocol/references/surface-design-authority.md`
## Examples and evals
- `examples/new-project/` — documentation foundation for a new project.
- `examples/handoff/` — brownfield multi-agent handoff showing a blocked material divergence.
- `examples/walkthrough-lite-copy-fix/` — Lite flow from request to narrow verification.
- `examples/walkthrough-standard-feature/` — Standard flow from request to current-work, plan, inspection, and handoff.
- `examples/walkthrough-critical-auth/` — Critical auth/security flow with risk, rollback, and release sign-off.
- `evals/` — zero-cost prompts and rubric for checking whether agents consume the protocol safely.
Run a local response check with:
```bash
python3 scripts/evaluate_agent_response.py --case critical-auth --response path/to/agent-response.md
```
## Installation
### Recommended global skill install
Install 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:
```bash
npx skills add phdigital01/structural-frame-protocol -g --copy
```
Target specific agents when needed:
```bash
npx skills add phdigital01/structural-frame-protocol -g --copy --agent claude-code codex opencode
```
The 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.
### Clean install from a checkout
For local development or Windows setups where you want a clean runtime-only skill folder, use the installer script instead of copying the whole repository:
```bash
python3 scripts/install_global_skill.py --target ~/.agents/skills/structural-frame-protocol
```
PowerShell:
```powershell
py scripts\install_global_skill.py --target "$env:USERPROFILE\.agents\skills\structural-frame-protocol"
```
The 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.
If 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:
```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
New-Item -ItemType Junction `
-Path "$env:USERPROFILE\.claude\skills\structural-frame-protocol" `
-Target "$env:USERPROFILE\.agents\skills\structural-frame-protocol"
```
### Hermes Agent
This repository remains Hermes-compatible. The expected skill entry point is:
```txt
skills/structural-frame-protocol/SKILL.md
```
For local Hermes profile sync, prefer the runtime installer pointed at the profile skill directory instead of a full-repo copy.
### Native skill agents
Use the runtime skill shape when the platform supports `SKILL.md` plus linked files:
```txt
structural-frame-protocol/
├── SKILL.md
├── references/
├── templates/
├── docs/
├── assets/
└── scripts/
```
The skill folder name must match the `name` in `SKILL.md` (`structural-frame-protocol`).
### Repository-instruction agents
For 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.
See:
- `skills/structural-frame-protocol/docs/07-agent-platform-compatibility.md`
- `skills/structural-frame-protocol/templates/platform-adapter.md`
## Publication roadmap
The 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.
Current channels and adapters:
- Global skill install through `npx skills add phdigital01/structural-frame-protocol -g --copy`.
- Hermes Skills Hub / local Hermes skill folders.
- Agent Skills format conformance (the standard `SKILL.md` shape), which keeps the skill portable across compatible clients.
- Third-party skill directories (ClawHub, GitHub registries) via `hermes skills publish`, pending acceptance.
- Repo-instruction adapters for Codex, Copilot, Cursor, Windsurf, Gemini CLI, Cline, Roo, and similar agents.
See `skills/structural-frame-protocol/docs/08-skill-library-publication.md` for gates, packaging rules, smoke tests, and registry records.
## Validation
```bash
python3 scripts/validate.py
python3 scripts/smoke_init.py
python3 scripts/install_global_skill.py --dry-run --target /tmp/skills/structural-frame-protocol
```
CI runs the same validation on pull requests.
## License
MIT. See [LICENSE](LICENSE).