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)#

IntentPriorityActionWhennew_journals50dispatch_scanFiles need eval-store bridgeexplicit_run80run_full_pipelineExplicit-run override detectedre_detection30closure_noopAll journals already in both eval stores

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#

ErrorHandlingclosure_closeout_check.py crashes (FileNotFoundError – <hermes-home> placeholder)Skip script. Manually verify gates: (1) grep bare relpath in both eval stores, (2) recompute max journal mtime programmatically + ≥2s pad, advance both monitor copies + praxis ingest_state.json, (3) re-assert verified_second_wave on all dispatch-owned files.run_mixed_wave_closure.py crashes (NameError: 'os')Handle closure manually. Same manual procedure as above.bridge_eval_inline.py crashes (FileNotFoundError)Manual JSONL append to both eval stores.forge_count_unprocessed.py returns 0 but dispatcher says genuineCross-check against prior forge-scan-*.json journal's unprocessed_proposals field.verify_eval_no_phantoms.py --fix run during closureSTOP. Historical phantoms are out of scope. Only fix date-scoped entries.Dispatch eval-store entries have wrong keyAll scanners must union filename/ journal_id/ journal/ journal_file keys.Mtime-advance truncation (hand-typed literal)Always recompute max(os.path.getmtime(p)) programmatically + ≥1s pad.Scripts with <hermes-home> placeholder crash on --helpNot a runtime failure — module-scope 3rd-party import before argparse..sh script permission deniedRun via bash script.sh --help instead of ./script.sh.

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#

FileWhen to Readreferences/design_pipeline.mdBefore forge.build (mandatory 8-phase pipeline)references/init_procedure.mdOn first invocation of any Forge commandreferences/authoring_rules.mdBefore writing/editing any SKILL.mdreferences/builder_workflows.mdBefore forge.verify-update, forge.consolidate, forge.sync, forge.auditreferences/dispatch-pipeline-guide.mdBefore running any dispatch pipeline or recoveryreferences/dispatch-integration-pitfalls-skillmd.mdCompanion to dispatch-pipeline-guide.mdreferences/dispatch-integration-detail.mdExpanded critical dispatch rules and recovery recipesreferences/gotchas-compact.mdWhen any dispatch operation or build encounters unexpected behaviorreferences/closure-script-path-placeholder-bug.mdWhen closure scripts crash with FileNotFoundErrorreferences/run-mixed-wave-closure-crash-os-import.mdWhen run_mixed_wave_closure.py crashesreferences/naming-and-authorship.mdBefore naming/renaming or setting authorreferences/enforcement_durability.mdWhen deciding absorption vs. new-skillreferences/interfaces.mdBefore processing VariantProposal/VariantDecision filesreferences/github_repo_guardrails.mdBefore creating any GitHub repo or PRreferences/storage-layout.mdWhen debugging data path issuesreferences/journal-file-path-construction.mdBefore writing any journal filereferences/phantom-file-cleanup.mdAfter every dispatch journal write runreferences/redetection-mtime-truncation-pitfall.mdWhen advancing gate state (mtime truncation trap)references/closure-email-state-refire-pitfalls.mdWhen closing mixed wave with email state filesreferences/closure-post-ingest-mtime-trap.mdAfter caller-journal write (Praxis ingest mtime gap)references/recover-dispatch-wave.mdPrior-wave-misclassification recovery (rewrite existing wave)scripts/forge_count_unprocessed.pySafe bounded count of unprocessed proposalsscripts/forge_audit_skills.pyOCAS compliance audit — run before any submissionscripts/bridge_eval_inline.pyIdempotent dual-store eval bridgescripts/closure_convergence_sweep.pyIterative gap-bridge loop (loop until 0 additions)scripts/closure_closeout_check.pyClosure gate verifier (all gates in one pass)scripts/bridge_explicit_run.pyCaller-side bridge for new_journals-ONLY dispatch wavesscripts/run_mixed_wave_closure.pyComplete mixed-wave closure runner (Forge+Mentor+Praxis+Taste)references/synthesis-methodology.mdWhen synthesizing a new skill from multiple sourcesreferences/sync_audit_procedure.mdBefore forge.sync-audit