sfs

name	sfs
description	Solon SFS command router for Codex. Dispatch `$sfs` / `sfs` / visible `/sfs` text to the deterministic SFS adapter (`sfs.cmd` on Windows PowerShell/cmd, `sfs` elsewhere), then read routed context with `sfs context cat ...` or native Windows `sfs.cmd context cat ...`. `profile` is a narrow SFS.md project-overview refinement.

Solon SFS — Codex Router

1. Prefer $sfs <command> or sfs <command>; /sfs is valid only if the text reaches the model. When executing on Windows PowerShell/cmd, use sfs.cmd <command>; use sfs <command> on macOS/Linux/Git Bash/WSL.
2. Run the platform adapter first: sfs.cmd <command> <args> on Windows PowerShell/cmd, otherwise sfs <command> <args>. Vendored fallback: bash .sfs-local/scripts/sfs-dispatch.sh <command> <args>.
3. If Windows execution sandboxing fails before SFS starts with Git Bash couldn't create signal pipe, Win32 error 5, rerun the same sfs.cmd ... command outside the sandbox. If the outside run is still empty or fails, report that exact stdout/stderr and ask for a PowerShell sfs.cmd --help sanity check instead of claiming success. For read-only fallback, use native sfs.cmd status, sfs.cmd version, and sfs.cmd context cat ...; these must not start Git Bash. If the runner cannot launch Git Bash, tell the user to run mutating commands in PowerShell/cmd.
4. Empty adapter output is not success for visible SFS commands. start, brainstorm, plan, implement, review, retro, adopt, profile, upgrade, and agent install must print output or change their expected artifact. For start, verify .sfs-local/current-sprint and the sprint directory exist before reporting success.
5. Keep adapter stdout/stderr verbatim.
6. Read sfs context cat kernel, sfs context cat index, then only the routed module. On Windows PowerShell/cmd use native sfs.cmd context cat ... so Git Bash is not started. Resolve command modules as sfs context cat commands/<command>.md (for example, commands/start.md) or via the command alias (sfs context cat start). For code/text/evidence search default to rg (ripgrep) instead of recursive grep; use plain grep only when rg is absent (see routed policies/search-tooling).
7. For bash-first commands, do not refine artifacts, but a compact state/Next is allowed. Compact output is quality-preserving only: remove filler in summaries/Next, but never compress adapter stdout/stderr, evidence, risk warnings, decisions, source links/paths, or raw-source traceability. If compactness would weaken quality, use full clarity.
8. For profile, edit only the SFS.md project overview section.
9. For hybrid commands, refine pointed artifacts and answer with one Solon report.
10. AI-era fundamentals and Harness Engineering are cross-phase. Before a gate advances, check shared design, domain language, feedback, boundaries, gray-box delegation, narrow tools, project-as-prompt, and automated checks. DDD/TDD is a product-level engineering floor: name product behavior, domain language, and first evidence before worker handoff; use DDD-lite boundaries when code is touched; keep invariants out of adapters; prefer failing, characterization, smoke, or review evidence before implementation. All product-bearing entrypoints are included: UI bootstraps, routers, root components, hooks/stores/effects, controllers, jobs, repositories, DTO mappers, CLI flags, scripts, migrations, docs wording, observability glue, and external adapters are not default homes for product policy without a named boundary, evidence, or explicit waiver. Natural-language SFS activation is real SFS: reconcile current user wording, latest handoff/docs, active sprint plan, and wiki/DDD maps; Approved sprint state never overrides a newer handoff or user intent, so evidence-backed conflicts are mis-scoped work, not user questions. Broad-entrypoint growth that adds product behavior during DDD/TDD work is a Gate 6 finding unless boundary extraction or approved deferral is recorded. Domain knowledge assets are first-class: compile expert know-how into source-linked glossaries/playbooks/skills/fixtures/wiki maps with owner/confidence/gaps and human-reviewed publication boundaries. Obsidian LLM wiki is a recommended companion for SFS continuity, not a hard dependency; load policies/obsidian-llm-wiki.md when setup/adoption/docs migration or multi-sprint retrieval is in scope. If .obsidian/ or llm-wiki/ exists, treat the wiki as active project context and update the relevant map or record a gap/waiver. Host-local tool/skill bundles and user-home folders are external environment, not project SSoT, wiki roots, install targets, or migration sources. Do not install, clone, scaffold, or promote them while building an Obsidian wiki unless the user explicitly asks; record references as external environment evidence only.
11. For implementation and review work, follow the routed context guardrails: surface material assumptions, choose the smallest useful slice, keep changes surgical, read actual files/errors before fixing, verify before completion, and report exact evidence; I/O-heavy verification/investigation uses a compressed-return worker for verdict, failing lines, core evidence paths, and risk while the lead keeps root-cause, attribution, and fix-shape judgment. User-facing docs HTML-encouraged: agent docs/logs/SSoT stay Markdown; real-user guides, reports, handbooks, onboarding, and landing docs render well in HTML but MD remains acceptable when GitHub-rendered MD is the primary read surface. For visible frontend/UI work, verify with Playwright or equivalent browser automation before asking the user to inspect it. Benchmarked engineering practices strengthen existing commands instead of creating new lifecycle commands: source-driven official docs, stop-the-line debugging, deprecation/migration, shipping/release checks, and review lenses source-docs, simplify, security, performance, api-contract, ddd-tdd. Release trigger contract: if the user says 배포해줘, treat it as 배포 프로세스 쭉 진행해줘, not a publish-only command. Load the release context and run readiness checks, relevant tests, review/검수, release cut, stable tag, Homebrew, Scoop, installed runtime verification, and evidence reporting end to end. Gate 3 (Plan) ready-for-implement routes to sfs review --gate 3 first; do not offer sfs implement or worker/model handoff until plan review passes. Keep C-Level and worker/generator responsibilities separate: C-Level owns intent, architecture, AC, and review handoff; worker/generator owns fixed implementation slices. Codex routing is role-specific: normal worker slices use gpt-5.4, helper I/O and non-coding helpers use gpt-5.4-mini, bounded repo-aware coding helpers use gpt-5.3-codex, and only locked judgment-free mechanical implementation helpers use gpt-5.3-codex-spark. Claude coding-capable worker/helper lanes use Sonnet 4.6; Haiku is non-coding helper-only. Gemini routes strategic/research/review to gemini-3.1-pro-preview, agentic coding/bounded implementation helpers to gemini-3-flash-preview, and relay/probe/economy helpers to gemini-3.1-flash-lite. Model routing applies by default, no user setup required. Helper-grade simple I/O is advisor-exempt. Focused question generation uses facilitator-standard models (Claude Sonnet 4.6, Codex gpt-5.4; Codex helper intake uses gpt-5.4-mini). Lower-model outputs that frame questions/options, interpret user answers, or affect product identity, architecture, gate, AC, or files_scope require top-model advisor review before gate advancement (Claude Opus 4.7, Codex gpt-5.5 xhigh, Gemini gemini-3.1-pro-preview). Complex shared behavior escalates to high reasoning before coding. Division sub-agent council is always-on from brainstorm through Gate 6: strategy-pm, dev, QA, design, infra, and taxonomy each records finding/evidence/waiver; actual parallel worker lanes remain opt-in. Multi-agent implement is optional, never the default: use single-agent mode unless the user selects parallel agents, each lane has disjoint files_scope, AC/ADR subset ownership, expected tests/evidence, output report path, merge/conflict policy, and a clear native-language commit message, and post-implement cross review is recorded before Gate 6. Commit messages default to the user's native/workspace language; English is only the default when that is the user or repo language. Gate 3 review must self-review until PASS before cross review. Review round count, lens count, or "enough review" is not a PASS; partial/fail routes to rework and same-gate self-review. If no other agent subscription exists, external agent tokens are exhausted, or the cross-review bridge is unavailable, a recorded self-CPO fallback PASS may satisfy the cross-review slot; a bare self-CPO PASS still blocks implementation unless the user explicitly waives the gate. If a partial/fail finding is deterministic and low-risk inside the brainstorm/plan contract, autopilot patch+verify+self-CPO/cross review. Never ask "진행?" / "proceed?" for missing self-CPO evidence, small guard/test/regex gaps, evidence paths, stale evidence, or meaning-preserving consistency. User-call minimalism: brainstorm + plan review define intent and decision boundaries. Ask only for new product judgment: scope, architecture, public contract, security/privacy/data-loss, cost/latency/model policy, destructive behavior, or changed AC meaning. User-escalation premise guard: before relaying any self/cross-review finding as a user question, normalize the premise and check it against brainstorm, plan, domain SoT, schema, code, and recorded decisions. If the premise is wrong, stale, already answered, or over-modeled, patch the artifact and re-review instead of forwarding the reviewer frame to the user. Do not invent ownership columns, cascade soft-delete, restore APIs, or migration policy unless the product contract requires them; prefer reject-delete-with-dependents when child records exist. Executable Action Ownership: when shell/tool/auth context and approval are available, run executable steps yourself and record evidence. Give copy-paste commands only when the user explicitly asks for them or when truly blocked by missing auth, unavailable tooling/runtime, sandbox or permission denial, uncaptured destructive/data-loss/public-contract approval, or materially broader scope than authorized. If the user grants session-scoped authorization such as 알아서 해, 이번 세션은 진행, or autonomous deploy, treat approval-gated steps in that scope as authorized for the current session and continue executing until scope changes or a true blocker appears. Shell state is agent-owned: use one-shot inline env and mask secrets instead of asking the user to export variables across terminals. Monitor checkpoint classification is mandatory for long-running monitor work: classify each checkpoint as progressing, slow, stalled, dead, or auth_blocked; record commit delta, PR/head delta, local dirty state, test/check delta, review status delta, worker liveness probe result, lane-utilization evidence or waiver, and next action wait, probe, revive, or close. Worker liveness requires a request-response probe, never process/auth-status alone. Use a static benign payload only, never workspace/user content, and persist only status/category/timestamp/redacted error class. Do not persist raw stdout/stderr, bearer/auth tokens, env vars, prompt bodies, model responses, workspace/user content, or PII. Close only after heartbeat/automation cleanup and durable wiki/report evidence. Handoff-only scope is a stop contract: if the user asks only for a handoff, next-session brief, session report, or 인계문서, immediately write/update that artifact, record current state/blockers/first next command, clean heartbeat/automation evidence when relevant, then stop; do not start or continue PR polling, review retriggers, merges, implementation, deploy, or monitor loops; interrupt active or queued batches and do not finish current PRs first unless the same user request explicitly asks to continue. If post-request PR/review/merge work already happened, report it as a scope breach, not as a justification. Advisor calls do not count as self-CPO. Before external cross review, record a self-CPO mini-check: requirements to AC to implementation slices to ADR/decision ids, every AC mapped to file/artifact/evidence, and SEED/ placeholder/mock/fallback material treated as non-acceptance until replaced. GitHub @codex PR/code review is external evidence only and post-implementation only; do not request, trigger, or count it during brainstorm or Gate 3 plan review. External review/check PASS is a continuation trigger, not a stopping point. Codex, Claude, Gemini, and future LLM agents must continue with the next unmet SFS review command. For Gate 6 implementation review, run sfs review --gate 6 --stage self, then sfs review --gate 6 --stage cross, then GitHub @codex as final external evidence when available unless a recorded self-CPO fallback reason covers no other agent subscription, external agent token exhaustion, or cross-review bridge unavailability. Session Continuation Guard: sfs upgrade updates runtime/project context but cannot shrink an already-open LLM conversation. If the host token meter is 30%+ before a new WU/sprint action, 50%+ before a new gate/loop/review handoff, or the same chat has spanned multiple WUs/sprints or repeated loop wakeups, stop and hand off to a fresh session using compact artifacts. Fresh-session transfer is lossless autopilot: write durable handoff/transfer capsule, invoke host-owned transfer/new-session/archive/clear+resume when available, and resume immediately; otherwise stop with exact prompt. Never ask user to type /clear or choose same-session vs fresh-session, and never call bare clear. After a work slice is implemented and verified, run self-agent top-model CPO: Claude Opus 4.7, Codex gpt-5.5 xhigh, Gemini gemini-3.1-pro-preview, or the configured custom top model. Partial/fail redirects the work and repeats until PASS or explicit user waiver. For Solon commit grouping, guide users to $sfs commit plan or sfs commit plan, then $sfs commit apply --group <name> or sfs commit apply --group <name>. sfs commit apply commits and pushes the current branch by default in user projects; use --no-push only for local sandbox/release testing or offline work. Do not route SFS work to a host-local /commit skill; /commit is not the portable SFS workflow command.
12. In Solon reports, show gates as Gate N (Name), not naked ids: Gate 1 (Intake), Gate 2 (Brainstorm), Gate 3 (Plan), Gate 4 (Design), Gate 5 (Handoff), Gate 6 (Review), Gate 7 (Retro). Use gate numbers 1..7 for new CLI examples.
13. Decision questions must be self-contained: before any Q1, D1, or option id, explain in plain user language what is being decided, why it matters, the recommended default, and what each option changes. Labels are cross-references, not the explanation.
14. Do not show a question/recommendation-only choice table. When multiple options exist, show every viable option with its plain-language meaning and consequence, then mark the recommendation as the default. If that is too much for one view, ask one decision at a time instead of hiding alternatives.
15. Never ask the user to confirm a compact option bundle such as A/A/A/C/C, and never answer "show the recommendation again" with only option labels or only the recommended row. Re-present the decision in plain language and use a natural confirmation phrase such as 권장안 그대로 확정, not a label bundle.
16. Taxonomy is a product function, not an org division or copy polish. Match the user's native/workspace language and project terms; do not machine-translate SFS command/domain terms into mixed phrases or expose app placeholder labels such as Other or Type something as product choices.
17. If a required command argument is missing, ask one plain-language question in the user's language instead of opening a multi-choice prompt. For Korean sfs start with no goal, ask: 이번 sprint 목표를 한 줄로 말해 주세요. 예: "docker compose 구조 리디자인".
18. For brainstorm, ask 1-3 blocking questions when shared understanding is missing. Do not run or recommend plan as the next step until Gate 2 is ready-for-plan.
19. For plan, derive the contract from brainstorm.md; unresolved Gate 2 questions stay visible instead of being hidden by assumptions.
20. For implement, backend architecture follows the routed implement.md guardrail: clean layered monolith for MVP/small projects, CQRS for non-initial backend work even on one DB, Hexagonal transition only after user acceptance, and MSA transition only after explicit approval.
21. For implement, non-Dev divisions also follow routed policy ladders: strategy-pm, taxonomy, design/frontend, QA, and infra start lightweight, strengthen on trigger evidence, and require user acceptance/approval before large roadmap, rename, redesign, release-readiness, or infra transitions.