Occas-Forge

Skill architect and builder. Given a capability idea or broken package, runs a mandatory eight-phase pipeline before writing files. Default output is the finished installable package — never returns design briefs or plans in place of real artifacts.

Every build starts with absorption check, research, and classification before a single file is created.

Why This Skill Exists

Forge is the only authorized skill builder in OCAS. Without it, agents would create skills with inconsistent structure, missing frontmatter, no tests, and no cross-skill coordination. The rigid pipeline ensures every skill meets OCAS standards and doesn't duplicate existing work.

When to Use

• Building new OCAS skills from scratch
• Skill architecture and design review
• Bulk skill library updates and synchronization
• Skill consolidation and deprecation
• Repair broken or defective skill packages
• Validate a skill package against OCAS standards

When NOT to Use

• Skill evaluation/scoring — use skilllab
• Variant proposals/experiments — use Mentor or Fellow
• System health monitoring — use Custodian
• One-off task execution — use the appropriate existing skill
• Web research — use Sift
• Authentication and MCP wiring — use ocas-auth
• Frontmatter reference/template lookup — use write-a-skill for quick field requirements
• Building non-skill artifacts

Pipeline

• Existence gate — check if skill already exists, absorption test
• Research — search GitHub + skill library for patterns; review ≥10 sources
• Classify — determine shortcut/workflow/system type
• Scope — define boundaries and interfaces
• Architecture — design package structure
• Plan — create implementation plan
• Build — implement the skill
• Validate — run critique and verify 50/50

Absorption first: If an existing skill already owns the domain, add content as a references/ doc or scripts/ file — do NOT create a new skill. See references/enforcement_durability.md.

Research is mandatory for ALL operations — not just new builds. When improving an existing skill, you MUST research external sources for new patterns.

Pre-Build Quality Linters (embedded in the Validate step, per spec-ocas-skill-improvements.md §5.1):

1. Frontmatter verification — validate required metadata fields (name, description, version, author).
2. Incident-log shape detection — flag skill descriptions / reference bodies overly dense in ephemeral issue numbers or quoted chat transcripts instead of generalizable rules.
3. Reference sprawl check — fail the build if references/ exceeds 60 files.
4. Config vs env separation — reject scripts that read behavioral configuration from os.environ instead of skills.config.<key> in config.yaml (reserving env vars strictly for credentials/secrets). Run all four before a new package is marked valid; a failing linter blocks promotion to production.

Commands

• forge.build — design, scope, build, validate a complete skill package
• forge.critique — review package and identify defects
• forge.repair — fix broken files in existing package
• forge.validate — run validation checks on a package
• forge.audit — audit one or more skills for OCAS compliance, apply fixes, sync to GitHub
• forge.consolidate — merge orphan/duplicate skill into natural parent
• forge.sync — sync local changes to canonical repository via PR
• forge.update — pull latest from GitHub source
• forge.status — current build state (multi-step)
• forge.journal — write journal for current run

Run completion: After every command, check for unprocessed VariantProposal/VariantDecision files in intake/, process new files, persist build logs to decisions.jsonl, write journal. Never report success until validation has actually executed — write_file/skill_manage(action='create') completing is NOT validation.

Triage Classification (dispatch)

Skill Type Classification

• Shortcut — narrow tool wrapper. 20-120 line SKILL.md.
• Workflow — multi-step process. 80-250 line SKILL.md.
• System — durable behavior system. 150-300 line SKILL.md + references.

Error Handling

Gotchas / Pitfalls

Key patterns in references/gotchas-compact.md. Critical at-a-glance:

• proposals//processed/ are SOURCE MIRRORS — use forge_count_unprocessed.py, never recursive walk
• <hermes-home> placeholder in closure scripts — skip, manual gate verify
• Eval-store grep uses bare relpath — never commons/journals/-prefixed
• JSON edits: write_file not patch — patch corrupts JSON structure
• Never recursive-glob commons/journals/** — symlink loops, use bounded per-skill globs
• Tool-layer flake on read/write tools — route to terminal() after 1-2 failures
• Mtime-advance: never hand-type literals — programmatic only
• Dispatch eval keys union ALL 4 variants — filename, journal_id, journal, journal_file
• Research is NOT optional for improvements — Phase 1.5 mandatory
• NEVER create/rename ocas-* without user authorization
• Absorption first — never create new skill when existing one owns the domain

Naming and Authorship Rules

See references/naming-and-authorship.md. Key: never create/rename to ocas-*/util-* without explicit authorization. Auto-generated skills use author: autogenerated.

Dispatch / Cron Integration

When triggered by dispatcher or forge:journal-scan cron:

• Check for unprocessed vp_*.json/vd_*.json in intake/ (use forge_count_unprocessed.py)
• Cross-reference against intake/processed/ and processed/
• Process new files; move to processed/
• If no unprocessed files: write no-op journal and exit
• Perform phantom file cleanup (see references/phantom-file-cleanup.md)

Full detail in references/dispatch-integration-detail.md and references/dispatch-pipeline-guide.md.

Self-Update

forge.update pulls from source: URL. Pre-drift check: git fetch origin; git log HEAD..origin/main and git diff --stat origin/main.

Support File Map