sica-fondt/ONBOARDING.md at 3919e70ed046513a186e48c69b207f1bdbf75a7c

mirror of https://github.com/SHOGGOTH-SECTOR/sica-fondt.git synced 2026-07-31 16:16:26 +00:00

Reorg step 2: move CLAUDE.md into core/, fix signpost refs

Move the canonical working-agreements file to core/CLAUDE.md (preserving
history) and leave a thin root CLAUDE.md pin that imports it so the
invariants still auto-load at the repo root. Update ONBOARDING.md's stale
docs/ paths to core/docs/. The move also fixes the core/src/*/AGENTS.md
links that pointed at ../../CLAUDE.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015hmgREHNsxYCuim33yUF2c

2026-06-23 16:15:22 +00:00

3.7 KiB

Raw Blame History

Your Setup Checklist

Codebases

sica-fondt — https://github.com/shoggoth-sector/sica-fondt

MCP Servers to Activate

GitHub — read/write PRs, issues, CI status, and code from GitHub without leaving Claude Code. Get access by connecting the GitHub MCP server in your Claude Code settings and authorizing the shoggoth-sector org.

Skills to Know About

/update-config — configure the Claude Code harness via settings.json (permissions, env vars, hooks). The team's most-used command; reach for it for any "from now on when X…" automation.
/session-start-hook — set up a SessionStart hook so the repo's toolchains/tests are ready in every web session. This repo uses one to install ponyc/Alire/GnuCOBOL.
/deep-research — fan-out, fact-checked, cited research reports when you need to investigate a topic in depth.
/fewer-permission-prompts — scan transcripts and add a read-only allowlist to .claude/settings.json to cut down on permission prompts.
/compact — free up context by summarizing the conversation so far on a long session.
/design-sync — keep the design docs and the architecture in step (used on this design-first repo).

Team Tips

Design before code. This is a design-first repo — the architecture docs are the source of truth and the code follows them. When something feels ambiguous, the answer is usually already written down; sync the design first (/design-sync).
The container is ephemeral; toolchains are reinstalled every session. A SessionStart hook (.claude/hooks/install-toolchains.sh) installs ponyc (via ponyup), Alire/GNAT, and GnuCOBOL on each session. If a build can't find ponyc, it's a PATH thing: export PATH=/root/.local/share/ponyup/bin:$PATH.
All external traffic crosses the Ada border (D1) first. That's the S1 structural invariant — never route around it, and never reclassify a message's provenance (S2). The Ichor bus rejects unscreened external payloads on purpose.
The invariant-law vault is immutable at runtime. Invariant 0 (the culpability anchor) and 01 (minimize harm) live in the COBOL vault and are not to be edited casually — they're the constitution, not config.
Verify by running, not just reading. Use /run-sica-fondt (or its smoke.sh) to build + run the Pony/Ada/COBOL units and confirm all green before you push.
Commit and push before you walk away. The stop hook will nag about untracked files for a reason — nothing survives the container otherwise.

Get Started

Your first task: get the project running end-to-end and read the map. Not sure which doc to read for what? Start with AGENTS.md — it's the directions for every other document here.

Open the repo and let the SessionStart hook finish installing toolchains.
Run the smoke driver to confirm everything builds and runs: .claude/skills/run-sica-fondt/smoke.sh — you want smoke: ALL GREEN.
Read README.md, and core/docs/ (start with core/docs/bus-topology.md and core/docs/gen03_state_of_architecture.md) to understand the organ/border model (Ichor bus → Ada D1 border → inner brain; the COBOL invariant vault).
Pick up a small design-sync or build task from there. Ask Claude to walk you through any unit — it has the run-sica-fondt skill loaded.

3.7 KiB Raw Blame History