From f3ee39bfbbd89941a5581255e3c3aa17d2bcc940 Mon Sep 17 00:00:00 2001 From: Martin Zeman Date: Sun, 14 Jun 2026 11:42:12 +0200 Subject: [PATCH] feat: model baseline context evaluation --- config/models.yaml | 28 +++ .../MVPR-0003 Dedicated Release Bundles.md | 7 +- ...-0004 Model Baseline Context Evaluation.md | 64 +++++ ...alifier Directories for Model Targeting.md | 8 +- docs/todos/2026-06-12.md | 6 + rules/AgentStructure.md | 9 - rules/ArtifactComposition.md | 12 - rules/BehavioralSteering.md | 16 +- rules/ClaudeCoworkLimitations.md | 11 - rules/CrossProviderAssembly.md | 13 - rules/DeployManifest.md | 8 - rules/Deslop.md | 18 ++ rules/DriftComparison.md | 8 - rules/GitCryptUserData.md | 22 -- rules/GitWorktrees.md | 10 +- rules/HookQuality.md | 7 - rules/HookScripts.md | 7 - rules/KeepFormatting.md | 4 +- rules/KnownIssues.md | 2 +- rules/LineEndings.md | 4 +- rules/MakefileFirst.md | 3 - rules/MemoryFiles.md | 4 +- rules/NoTabs.md | 2 +- rules/NoVendorLockIn.md | 9 + rules/ProvenanceVerification.md | 7 - rules/RuleStructure.md | 8 +- rules/ScanRepository.md | 1 - rules/SecretScan.md | 10 - rules/SelfLearning.md | 4 +- rules/UseForge.md | 2 +- rules/UseRTK.md | 4 +- rules/ValidationChain.md | 7 - rules/WindowsConstraints.md | 3 - .../ExplicitToolUse.md | 0 .../ScopeAwareness.md | 0 .../ToolVerification.md | 0 .../AvoidDuplication.md | 0 .../ProportionalEffort.md | 0 .../claude-opus-4-7/BehavioralSteering.md | 23 ++ .../claude-opus-4-7}/DeadVariables.md | 0 .../claude-opus-4-7}/NeverRefuseWork.md | 0 .../PrepareDataOutsideLoops.md | 0 .../claude-opus-4-8/BehavioralSteering.md | 23 ++ rules/claude/claude-opus-4-8/DeadVariables.md | 1 + .../claude/claude-opus-4-8/NeverRefuseWork.md | 1 + .../PrepareDataOutsideLoops.md | 1 + .../AssertiveFindings.md | 0 .../ReviewDiscipline.md | 0 .../OutputDiscipline.md | 0 .../claude-sonnet-4-6/ReviewDiscipline.md | 3 + rules/gemini/AgentStructure.md | 11 - skills/AdoptArtifact/SKILL.md | 23 +- skills/ArchitectureDecision/Example.md | 41 ---- skills/ArchitectureDecision/SKILL.md | 25 +- .../ArchitectureDecision/SchemaValidation.md | 6 +- .../ArchitectureDecision/TemplateReference.md | 17 +- skills/ArchitectureDecision/user/ForgeADR.md | 19 -- skills/BashConventions/BashPatterns.md | 227 +----------------- skills/Brainstorming/SKILL.md | 14 +- skills/BuildAgent/ClaudeAgent.md | 22 +- skills/BuildAgent/GeminiAgent.md | 6 +- skills/BuildAgent/SKILL.md | 48 ++-- skills/BuildHook/SKILL.md | 26 +- skills/BuildModule/CodexProvider.md | 14 +- skills/BuildModule/GeminiProvider.md | 12 - skills/BuildModule/InstallGuide.md | 40 +-- skills/BuildModule/LinuxPlatform.md | 2 +- skills/BuildModule/ModuleStructure.md | 28 +-- skills/BuildModule/OpenCodeProvider.md | 14 +- skills/BuildModule/SKILL.md | 76 +++--- skills/BuildModule/VERIFY.mdschema | 18 -- skills/BuildModule/VerifyGuide.md | 41 ---- skills/BuildModule/WindowsPlatform.md | 6 +- skills/BuildModule/macOSPlatform.md | 2 +- skills/BuildPlugin/ClaudeMarketplace.md | 27 +-- .../BuildPlugin/ClaudePlugin.md | 4 +- skills/BuildPlugin/SKILL.md | 3 +- skills/BuildSkill/PlatformAgnostic.md | 2 + skills/BuildSkill/SKILL.md | 1 + skills/ExecutePlan/SKILL.md | 11 - skills/GuardRails/SKILL.md | 8 +- skills/GuardRails/SafetyNet.md | 56 ----- skills/GuardRails/SafetyOverride.md | 16 -- skills/GuardRails/SecurityReview.md | 13 +- skills/HtmlPlayground/SKILL.md | 36 +-- skills/LearnFrom/SKILL.md | 15 +- skills/MarkdownConventions/Example.md | 108 --------- skills/MarkdownConventions/Linting.md | 21 +- skills/MarkdownConventions/SourceCitations.md | 2 - skills/OptimizeContext/SKILL.md | 95 ++++++++ skills/ProjectBacklog/Example.md | 2 - skills/ProjectBacklog/SKILL.md | 40 +-- skills/ProvenanceAudit/SKILL.md | 52 ++-- skills/RTK/SKILL.md | 26 +- skills/RefinePrompt/Adapt.md | 14 +- skills/RefinePrompt/Align.md | 8 +- skills/RefinePrompt/Debrand.md | 2 - skills/RefinePrompt/Rescope.md | 16 +- skills/ResearchTopic/SKILL.md | 11 +- skills/SecretScan/SKILL.md | 42 +++- skills/SessionSearch/Entire.md | 2 +- skills/SessionSearch/SKILL.md | 11 +- skills/StagedReview/SKILL.md | 8 +- skills/SystemCheck/SKILL.md | 36 ++- 104 files changed, 576 insertions(+), 1230 deletions(-) create mode 100644 config/models.yaml create mode 100644 docs/decisions/MVPR-0004 Model Baseline Context Evaluation.md create mode 100644 docs/todos/2026-06-12.md delete mode 100644 rules/AgentStructure.md delete mode 100644 rules/ArtifactComposition.md delete mode 100644 rules/ClaudeCoworkLimitations.md delete mode 100644 rules/CrossProviderAssembly.md delete mode 100644 rules/DeployManifest.md create mode 100644 rules/Deslop.md delete mode 100644 rules/DriftComparison.md delete mode 100644 rules/GitCryptUserData.md delete mode 100644 rules/HookQuality.md delete mode 100644 rules/HookScripts.md delete mode 100644 rules/MakefileFirst.md create mode 100644 rules/NoVendorLockIn.md delete mode 100644 rules/ProvenanceVerification.md delete mode 100644 rules/ScanRepository.md delete mode 100644 rules/SecretScan.md delete mode 100644 rules/ValidationChain.md delete mode 100644 rules/WindowsConstraints.md rename rules/claude/{haiku => claude-haiku-4-5}/ExplicitToolUse.md (100%) rename rules/claude/{haiku-4-5 => claude-haiku-4-5}/ScopeAwareness.md (100%) rename rules/claude/{opus-4-5 => claude-opus-4-5}/ToolVerification.md (100%) rename rules/claude/{opus-4-6 => claude-opus-4-6}/AvoidDuplication.md (100%) rename rules/claude/{opus-4-6 => claude-opus-4-6}/ProportionalEffort.md (100%) create mode 100644 rules/claude/claude-opus-4-7/BehavioralSteering.md rename rules/{ => claude/claude-opus-4-7}/DeadVariables.md (100%) rename rules/{ => claude/claude-opus-4-7}/NeverRefuseWork.md (100%) rename rules/{ => claude/claude-opus-4-7}/PrepareDataOutsideLoops.md (100%) create mode 100644 rules/claude/claude-opus-4-8/BehavioralSteering.md create mode 100644 rules/claude/claude-opus-4-8/DeadVariables.md create mode 100644 rules/claude/claude-opus-4-8/NeverRefuseWork.md create mode 100644 rules/claude/claude-opus-4-8/PrepareDataOutsideLoops.md rename rules/claude/{sonnet-4-5 => claude-sonnet-4-5}/AssertiveFindings.md (100%) rename rules/claude/{sonnet => claude-sonnet-4-5}/ReviewDiscipline.md (100%) rename rules/claude/{sonnet-4-6 => claude-sonnet-4-6}/OutputDiscipline.md (100%) create mode 100644 rules/claude/claude-sonnet-4-6/ReviewDiscipline.md delete mode 100644 rules/gemini/AgentStructure.md delete mode 100644 skills/ArchitectureDecision/Example.md delete mode 100644 skills/BuildModule/VERIFY.mdschema delete mode 100644 skills/BuildModule/VerifyGuide.md rename rules/ClaudePluginStructure.md => skills/BuildPlugin/ClaudePlugin.md (85%) delete mode 100644 skills/GuardRails/SafetyNet.md delete mode 100644 skills/GuardRails/SafetyOverride.md delete mode 100644 skills/MarkdownConventions/Example.md create mode 100644 skills/OptimizeContext/SKILL.md diff --git a/config/models.yaml b/config/models.yaml new file mode 100644 index 0000000..89aed44 --- /dev/null +++ b/config/models.yaml @@ -0,0 +1,28 @@ +# Valid provider and model identifiers for this module. +# Qualifier directory names under rules// must match these IDs exactly. +# Update when providers release new models. + +claude: + - claude-fable-5 + - claude-opus-4-8 + - claude-opus-4-7 + - claude-opus-4-6 + - claude-opus-4-5 + - claude-sonnet-4-6 + - claude-sonnet-4-5 + - claude-haiku-4-5 + +codex: + - gpt-5.3-codex + - gpt-5.4 + - gpt-5.5 + +gemini: + - gemini-2.5-pro + - gemini-2.5-flash + - gemini-2.0-flash + +opencode: + - claude-fable-5 + - claude-opus-4-8 + - claude-sonnet-4-6 diff --git a/docs/decisions/MVPR-0003 Dedicated Release Bundles.md b/docs/decisions/MVPR-0003 Dedicated Release Bundles.md index a90ee8f..9e6bd6c 100644 --- a/docs/decisions/MVPR-0003 Dedicated Release Bundles.md +++ b/docs/decisions/MVPR-0003 Dedicated Release Bundles.md @@ -8,10 +8,11 @@ tags: - deployment status: proposed created: 2026-03-16 -updated: 2026-03-30 +updated: 2026-06-11 author: "@N4M3Z" project: forge-core -related: [] +related: + - "PROV-0005 Qualifier Directories for Model Targeting.md" responsible: ["@N4M3Z"] accountable: ["@N4M3Z"] consulted: [] @@ -43,6 +44,8 @@ releases/ forge-core-opencode-v0.6.0.tar.gz ``` +Where model-level qualifier variants exist ([PROV-0005](PROV-0005%20Qualifier%20Directories%20for%20Model%20Targeting.md)), the release matrix extends per model: one bundle per provider and model ID, assembled with `--model ` and archived as `---v.tar.gz`. A bundle built without `--model` uses base resolution. The bundle's `.manifest` records the target provider and model, so integrity checks also verify which model variant a deployment received. + Each bundle contains: ``` diff --git a/docs/decisions/MVPR-0004 Model Baseline Context Evaluation.md b/docs/decisions/MVPR-0004 Model Baseline Context Evaluation.md new file mode 100644 index 0000000..81de546 --- /dev/null +++ b/docs/decisions/MVPR-0004 Model Baseline Context Evaluation.md @@ -0,0 +1,64 @@ +--- +title: Model Baseline Context Evaluation +description: The running model self-assesses loaded context against its own baseline, with verification rails and qualifier-directory parking +type: adr +category: architecture +tags: + - architecture + - prompts +status: accepted +created: 2026-06-12 +updated: 2026-06-12 +author: "@N4M3Z" +project: forge-core +related: + - "MVPR-0001 Minimum Viable Prompt.md" + - "MVPR-0002 Prompt Minimalization Metrics.md" + - "PROV-0005 Qualifier Directories for Model Targeting.md" +responsible: ["@N4M3Z"] +accountable: ["@N4M3Z"] +consulted: [] +informed: [] +upstream: [] +--- + +# Model Baseline Context Evaluation + +## Context and Problem Statement + +Always-on instructions accumulate for the weakest model that ever needed them. As frontier models internalize behaviors through training and harness prompts (read-before-assert, verify-before-done, scope discipline), the rules written to compensate become permanent token cost with no behavioral effect, and nothing in the toolchain distinguishes "still steering" from "internalized." MVPR-0001 demands a minimum viable prompt per model; MVPR-0002 supplies static scans and on-demand ablation. Neither answers the operational question a new flagship raises: which loaded instructions can this model drop, and where does the dropped content go so weaker models keep it? + +## Considered Options + +- **Manual curation per model release** — re-read every rule by hand; does not scale and has no test +- **Static scan only** — MVPR-0002 scan mode; catches structure, staleness, and conflicts but cannot measure whether the running model needs an instruction +- **Ablation for everything** — PromptFoo with/without per rule per model; accurate but slow and expensive as a default path +- **Baseline self-assessment with verification rails** — the running model evaluates its own loaded context, bounded by rails that counter its bias + +## Decision Outcome + +Chosen option: **baseline self-assessment with verification rails**, implemented as the OptimizeContext skill. + +The running model applies a behavioral test to each loaded instruction: "if this instruction were absent, would my unprompted output already satisfy it?" Knowing is not complying; the test is on behavior, not comprehension. Content divides into three kinds with different verdict spaces: + +| Kind | Test | Verdicts | +| ------------------- | ----------------------------------------------- | ------------------------------------- | +| Capability steering | behavioral test against the session baseline | offload, keep | +| Preference, policy | user choices no model can infer | slim, stale-fix, keep (never removed) | +| Knowledge reference | does this belong in always-on context at all? | relocate to a lazy skill, stale-fix, keep | + +The rails are part of the decision, not implementation detail: + +- **Nothing is destroyed by capability reasoning.** Offload parks the full text in model qualifier directories ([PROV-0005](PROV-0005 Qualifier Directories for Model Targeting.md)) for the models that still need it; deletion requires the content to be wrong or stale, and explicit confirmation. +- **The evaluator is biased toward a smaller context.** Verdicts below high confidence escalate to ablation ([MVPR-0002](MVPR-0002 Prompt Minimalization Metrics.md)) instead of acting; every duplication or staleness claim is verified against the repository before application; every proposal is confirmed individually by the user. +- **Agents are evaluated against their pinned model tier, never the session model.** A fast-tier agent still needs scaffolding the session model does not. +- **Rules are evaluated first.** They cost tokens in every session; skill bodies are lazy and are trimmed only for dead weight, while their reference and policy content is protected. +- **Knowledge migrates down the loading ladder.** Reference material found in always-on rules relocates into the owning skill, loading only when the skill fires. + +## Consequences + +- Positive: context shrinks as models improve instead of growing monotonically +- Positive: older models keep their full instruction sets through qualifier parking +- Positive: reference content moves from always-on rules to lazy skills, sharpening the rules/skills split +- Tradeoff: self-assessment is a weak signal; the confidence bar and ablation escalation are load-bearing, not optional +- Tradeoff: the evaluation recurs at every model generation; it is an operating practice, not a one-time cleanup diff --git a/docs/decisions/PROV-0005 Qualifier Directories for Model Targeting.md b/docs/decisions/PROV-0005 Qualifier Directories for Model Targeting.md index e49111b..7f4c846 100644 --- a/docs/decisions/PROV-0005 Qualifier Directories for Model Targeting.md +++ b/docs/decisions/PROV-0005 Qualifier Directories for Model Targeting.md @@ -8,7 +8,7 @@ tags: - targeting status: accepted created: 2026-03-15 -updated: 2026-03-30 +updated: 2026-06-11 author: "@N4M3Z" project: forge-core related: [] @@ -27,7 +27,7 @@ Models evolve under your feet. Instructions essential for one model version beco ## Considered Options -- **Qualifier directories** — `rules/claude/opus4.5/Rule.md` overrides the base `rules/Rule.md` +- **Qualifier directories** — `rules/claude/claude-opus-4-6/Rule.md` overrides the base `rules/Rule.md` - **Frontmatter targets** — `targets: [claude]` for include/exclude filtering - **Config-driven** — `defaults.yaml` enumerates which rules deploy to which providers - **Filename convention** — `Rule.claude.md` suffix-based variants @@ -36,7 +36,7 @@ Models evolve under your feet. Instructions essential for one model version beco Chosen option: **qualifier directories + frontmatter targets**, because they solve different problems and compose cleanly. -**Qualifier directories** handle content variants. Same filename in a subdirectory named after a provider or model overrides the base. Resolution precedence: `user/` > `provider/model/` > `provider/` > base. Valid qualifier names come from `defaults.yaml` providers config; `user/` is always valid (gitignored, personal overrides). +**Qualifier directories** handle content variants. Same filename in a subdirectory named after a provider or model overrides the base. Resolution precedence: `user/` > `provider/model/` > `provider/` > base. Valid provider qualifiers come from the providers config; valid model qualifiers are the exact model IDs listed in `config/models.yaml`, so the directory name is the model ID itself (`rules/claude/claude-opus-4-6/Rule.md`). No aliases, no segment matching. `user/` is always valid (gitignored, personal overrides). An unrecognized subdirectory inside a qualifier directory is a validation error: silent omission would drop content from deployment without trace. ``` rules/ @@ -46,6 +46,8 @@ rules/ user/AgentTeams.md # personal override ``` +**Skills** carry qualifier overlays inside the skill directory, reusing the `user/` flatten mechanics: `skills/Name///SKILL.md` overrides `skills/Name/SKILL.md` per file at assembly. Top-level qualifier directories under `skills/` are not valid; the skill directory name must always match the skill's `name:` field. + **Frontmatter targets** handle include/exclude. A rule that applies to some providers but not others declares `targets:` in frontmatter, stripped at deploy. This also serves as a reconstructibility record — if qualifier directories are lost, the frontmatter documents which providers the rule was meant for. ```yaml diff --git a/docs/todos/2026-06-12.md b/docs/todos/2026-06-12.md new file mode 100644 index 0000000..a9d2def --- /dev/null +++ b/docs/todos/2026-06-12.md @@ -0,0 +1,6 @@ +# Todos — 2026-06-12 + +- [ ] Run PromptAnalysis ablation on the rules escalated by the model baseline scan [priority:: medium] [id:: 0001] #rules #mvpr + - Self-assessment scored these medium confidence; per MVPR-0004 they act only after behavioral confirmation. + - Candidates: AvoidDuplication, LessIsMore, NullableTypeSafety, PosixTrailingNewline, TestCorrectness, plus slim proposals for BehavioralSteering, HashVerifiedExecution, InstallInstructions, ShellAliases, VerifyClaims. + - Acceptance: each candidate has an ablation verdict (redundant or load-bearing) recorded, and confirmed-redundant ones are offloaded per PROV-0005. diff --git a/rules/AgentStructure.md b/rules/AgentStructure.md deleted file mode 100644 index b1b5f3d..0000000 --- a/rules/AgentStructure.md +++ /dev/null @@ -1,9 +0,0 @@ -Agents run in separate sessions with their own context window. They are invoked by delegation — the AI spawns them when the task matches the description, or the user selects them explicitly. They do not share the parent session's conversation history. - -An agent is a single `.md` file in `agents/`. Flat directory, no subdirectories. - -Frontmatter carries `name`, `description` (with USE WHEN triggers), and optionally `model`, `tools`, `disallowedTools`, `permissionMode`, `maxTurns`, `effort`, `skills`, `memory`, `isolation`, `color`, `hooks`, `mcpServers` ([Claude Code docs][CCDOCS]). - -Body follows a fixed structure: Role, Expertise, Instructions, Output Format, Constraints. The `agents/.mdschema` enforces this. - -[CCDOCS]: https://code.claude.com/docs/en/agents diff --git a/rules/ArtifactComposition.md b/rules/ArtifactComposition.md deleted file mode 100644 index 6ff28b7..0000000 --- a/rules/ArtifactComposition.md +++ /dev/null @@ -1,12 +0,0 @@ -Forge modules follow the **Agent Skills** ([agentskills.io][SKILLS]) standard for cross-provider compatibility. - -Modules produce three artifact types: -- **Rules**: Always loaded behavioral instructions. -- **Skills**: Lazy-loaded capabilities invoked by the AI. -- **Agents**: Persona definitions for delegation. - -Each artifact is authored once as Markdown in its respective directory (`rules/`, `skills/`, or `agents/`). - -Assembly transforms these canonical sources for each target provider — see [CrossProviderAssembly][CrossProviderAssembly.md] for the assembly pipeline specifics. - -[SKILLS]: https://agentskills.io "Agent Skills Standard" diff --git a/rules/BehavioralSteering.md b/rules/BehavioralSteering.md index 225ef93..956120f 100644 --- a/rules/BehavioralSteering.md +++ b/rules/BehavioralSteering.md @@ -1,20 +1,8 @@ These thoughts mean STOP — you're rationalizing a bad decision: -| Thought | Reality | -| ---------------------------------------- | ---------------------------------------------------------------- | -| "This is just a small change" | Small changes have big blast radii. Verify before claiming done. | -| "I'll clean this up while I'm here" | Scope creep. Do what was asked, then stop. | -| "I know what this code does" | Read it. Memory lies. Verify before asserting. | -| "Tests aren't needed for this" | If it can break, it needs a test. | -| "Let me add error handling just in case" | Don't guard against scenarios that can't happen. | -| "I'll create a helper for this" | Three similar lines beat a premature abstraction. | -| "I'll write a function to do X" | Check if X already exists. Scaffold around it instead of reimplementing. | -| "The user probably wants me to also..." | Do what was asked. Ask before expanding. | -| "I can skip reading the file" | Read before claiming. Every shortcut is a future bug. | -| "Quick fix for now, investigate later" | Root cause first. Symptom fixes create new bugs. | -| "I'm confident it works" | Confidence is not evidence. Run the command. | +| Thought | Reality | +| ---------------------------------------- | ------------------------------------------------------------------------ | | "Propose the full framework, then trim" | First pass gets heavily cut. Start minimal; scope up on demand. | -| "I know how this tool or format works" | External-behavior claims need evidence. Read docs or say you're unsure. | | "I'll design what should exist here" | Scan existing skills and modules first. New usually collides with old. | | "This short message clearly means X" | Short messages are easy to misread. Re-read before acting on new work. | | "More detail is safer than less" | Bloat is unsafe. Fewer structured points beat a longer response. | diff --git a/rules/ClaudeCoworkLimitations.md b/rules/ClaudeCoworkLimitations.md deleted file mode 100644 index fb17fb9..0000000 --- a/rules/ClaudeCoworkLimitations.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -targets: [claude] ---- -Cowork silently drops all plugin hooks. The CLI is spawned with `--setting-sources user`, which excludes plugin-scoped hook discovery ([GitHub #27398][ISSUE]). All hook types (command, prompt, agent) are affected. No error is surfaced. - -Skills, agents, and MCP servers work in Cowork ([plugins reference][PLUGINS]). Hooks are unsupported at this time. - -Any behavior that must work in Cowork cannot rely on hooks. Ship it as a rule (always loaded) or a skill (user-invoked) instead. - -[ISSUE]: https://github.com/anthropics/claude-code/issues/27398 -[PLUGINS]: https://code.claude.com/docs/en/plugins-reference diff --git a/rules/CrossProviderAssembly.md b/rules/CrossProviderAssembly.md deleted file mode 100644 index 62ab22a..0000000 --- a/rules/CrossProviderAssembly.md +++ /dev/null @@ -1,13 +0,0 @@ -The `forge install` command (via `forge-cli`) transforms canonical source artifacts for each target provider using a standardized assembly pipeline. - -### Assembly Pipeline - -1. **Translation**: Converts Markdown agent files into provider-native formats (e.g., TOML for Gemini and Codex). -2. **Remapping**: Automatically translates standard tool names (e.g., `Read`, `Bash`, `Grep`) in `defaults.yaml` and agents into their native equivalents for each provider (e.g., `read_file`, `run_shell_command`). -3. **Cleanup**: Strips frontmatter, resolves companion files (`@`), and removes provenance markers to minimize token overhead in deployed files. - -Authors MUST author using the canonical Markdown form and standard tool names. Never write provider-specific formats (TOML) or use native tool names directly in the source repository. - -Assembly also rewrites provenance sidecars. Source-side `adopt/v1` sidecars (with upstream + AdoptArtifact dependencies) become `assemble/v1` sidecars at deploy, with a single-source input. The full adoption chain is preserved only in the source repo's `.provenance/` files. Audit deployed artifacts for tamper; audit source-repo sidecars for adoption history. See the [ProvenanceAudit][ProvenanceAudit] skill for operational procedures. - -[ProvenanceAudit]: skills/ProvenanceAudit/SKILL.md diff --git a/rules/DeployManifest.md b/rules/DeployManifest.md deleted file mode 100644 index e2b63a3..0000000 --- a/rules/DeployManifest.md +++ /dev/null @@ -1,8 +0,0 @@ -Manifest and provenance answer different questions: - -- **Provenance**: "what produced this file?" -- **Manifest**: "was this deployed file modified since we last put it there?" - -The manifest is created when files land at the target, whether via `forge deploy` (from `build/`) or `forge copy` (direct from source). It lives at the target as a `.manifest` dotfile. - -Provenance lives at two layers. Source-side `.provenance/` records adoption (`adopt/v1`): upstream URL, pinned commit, transform skills applied. Build-side `build//.provenance/` records assembly (`assemble/v1`), regenerated on every install. diff --git a/rules/Deslop.md b/rules/Deslop.md new file mode 100644 index 0000000..98ff2e2 --- /dev/null +++ b/rules/Deslop.md @@ -0,0 +1,18 @@ +Write like a human talking to a colleague. Slop is text that performs the act of answering instead of informing: it pads, inflates, and hedges. Strip it everywhere: prose, docs, commit messages, reviews, READMEs. + +Vocabulary tells ([Wikipedia catalog][WPSIGNS]): delve, tapestry, testament, underscore, pivotal, crucial, robust, vibrant, landscape, intricate, meticulous, boasts, showcase, harness, leverage, seamless, cutting-edge, game-changer. If a sentence needs one of these, it usually needs a fact instead. + +Construction tells: + +- Negative parallelism ("It's not just X, it's Y") manufacturing fake epiphany +- Rule-of-three adjective stacks ("fast, reliable, and scalable") +- Copula avoidance ("serves as", "stands as", "marks") where "is" works +- Participle tails attaching unverified significance ("...creating a vibrant community") +- Bold-every-keyword formatting and bullet lists where each bullet restates its heading +- Throat-clearing openers ("Certainly!", "Great question") and canned outros ("In conclusion", "I hope this helps") +- Weasel attribution ("experts argue", "observers note") without a named source +- Emoji in technical content, commits, code, or documentation + +Human test: read it aloud. If you would not say it to a colleague, rewrite it. If deleting the sentence loses nothing, delete it. + +[WPSIGNS]: https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing diff --git a/rules/DriftComparison.md b/rules/DriftComparison.md deleted file mode 100644 index c70c665..0000000 --- a/rules/DriftComparison.md +++ /dev/null @@ -1,8 +0,0 @@ -`forge drift` compares any two directories containing markdown content — modules, build output, or deployed targets. - -```sh -forge drift . ~/upstream-module # source vs upstream -forge drift build/claude ~/.claude # assembled vs deployed -``` - -Do not compare source against deployed content directly — assembly transforms (frontmatter stripping, heading removal) will always show as drift. Compare `build/` against the target instead. diff --git a/rules/GitCryptUserData.md b/rules/GitCryptUserData.md deleted file mode 100644 index 18c39fc..0000000 --- a/rules/GitCryptUserData.md +++ /dev/null @@ -1,22 +0,0 @@ -Modules with user-specific data (credentials, personal identifiers, insurance numbers) use git-crypt to encrypt those files in the public repo. Files are plaintext locally, encrypted blobs on push. - -Setup: - -```sh -brew install git-crypt -cd module-root -git-crypt init -git-crypt add-gpg-user YOUR_GPG_KEY_ID -``` - -Add a `.gitattributes` entry for the encrypted path: - -``` -rules/user/** filter=git-crypt diff=git-crypt -``` - -Remove `rules/user/` from `.gitignore` after git-crypt is configured — the files are now safe to commit. - -The `rules/user/` directory holds per-user data that the module's skills need at runtime (insurance identifiers, API account slugs, tax office codes) but must not be readable in the public repo. - -Until git-crypt is configured, `rules/user/` stays gitignored as a fallback. diff --git a/rules/GitWorktrees.md b/rules/GitWorktrees.md index d4c7f63..e7c8404 100644 --- a/rules/GitWorktrees.md +++ b/rules/GitWorktrees.md @@ -1,11 +1,3 @@ -Use git worktrees for parallel feature work instead of stashing or switching branches. Each worktree gets its own working directory with a shared `.git` store -- no context switching, no stash conflicts. - -```sh -git worktree add .worktrees/feature-branch feature-branch -git worktree remove .worktrees/feature-branch -git worktree list -``` - -Worktrees live in `.worktrees/` inside the repo, ignored by `.gitignore`. Add `.worktrees/` to `.gitignore` before creating the first worktree so the parallel checkouts do not appear in `git status` of the main tree. The sibling-directory pattern (`../repo-branchname`) also works but pollutes the parent directory and breaks paths in IDE workspaces and editor projects. +Use git worktrees for parallel feature work instead of stashing or switching branches. Worktrees live in `.worktrees/` inside the repo; add `.worktrees/` to `.gitignore` before creating the first worktree. Setup, safety checks, and cleanup mechanics: [GitWorktrees companion](../skills/VersionControl/GitWorktrees.md). When spawning agents for parallel implementation, use `isolation: "worktree"` so each agent works on an isolated copy without conflicting with the main tree or other agents. diff --git a/rules/HookQuality.md b/rules/HookQuality.md deleted file mode 100644 index 84d08ff..0000000 --- a/rules/HookQuality.md +++ /dev/null @@ -1,7 +0,0 @@ -Hooks must block or inject, never advise. A hook that "reminds" or "nudges" is a rule or skill in disguise. - -Before proposing a hook, check: does Claude Code already inject this context? Rules are always loaded. Skills are auto-discovered. Don't duplicate what the runtime provides. - -Kill test: if a hook breaks silently and nobody notices for a month, it wasn't worth shipping. - -See [ARCH-0011](docs/decisions/ARCH-0011 Hook Design Principles.md) for the full design criteria. diff --git a/rules/HookScripts.md b/rules/HookScripts.md deleted file mode 100644 index a5011ab..0000000 --- a/rules/HookScripts.md +++ /dev/null @@ -1,7 +0,0 @@ -Hook scripts MUST exit 0 always. A non-zero exit crashes the hook silently — Claude Code treats it as a hook failure, not a block decision. Communication is via stdout JSON only — stderr is invisible to Claude Code. - -- Empty stdout = allow -- `{"decision":"block","reason":"..."}` = block (Stop) -- `{"hookSpecificOutput":{"additionalContext":"..."}}` = AI context injection (PostToolUse) - -Guard files use `$PPID` or `$SESSION_ID` scoping to prevent repeat firing within a session. diff --git a/rules/KeepFormatting.md b/rules/KeepFormatting.md index b0de778..4101a3c 100644 --- a/rules/KeepFormatting.md +++ b/rules/KeepFormatting.md @@ -1,3 +1 @@ -4-space indentation everywhere — YAML, config files, all structured content. - -Liberal linebreaks between sections for readability — blank lines separate logical groups. +Liberal linebreaks between sections for readability: blank lines separate logical groups. diff --git a/rules/KnownIssues.md b/rules/KnownIssues.md index 6025906..7fa1400 100644 --- a/rules/KnownIssues.md +++ b/rules/KnownIssues.md @@ -1,6 +1,6 @@ Do not symlink plugins into the cache — Claude Code periodically wipes `~/.claude/plugins/cache/`. -`ekctl` (EventKit CLI) and other data-gathering tools (slackdump, DiscordChatExporter.Cli, sqlite3, m365) are pre-approved in `sandbox.excludedCommands` in both `settings.json` and `settings.local.json`. macOS TCC permissions are separate and must also be granted for EventKit tools. +macOS TCC permissions are separate from Claude Code sandbox and permission settings: EventKit tools (`ekctl`) need their own TCC grant even when the command itself is allowed. Subagents spawned with `mode: 'auto'` cannot write to git submodule paths even with `bypassPermissions`. Symptom: agent reports completion but no files were created. Workaround: do the writes from the parent session, or accept the permission prompt manually when it surfaces. diff --git a/rules/LineEndings.md b/rules/LineEndings.md index f1a6144..f172594 100644 --- a/rules/LineEndings.md +++ b/rules/LineEndings.md @@ -1,3 +1 @@ -Every repo should have a `.gitattributes` with `* text=auto eol=lf`. Files exported from Windows tools (SQL Server, Excel) arrive as UTF-16LE with CRLF — normalize to UTF-8 LF before committing. - -When encountering binary diffs on text files (git shows `- -` instead of line counts), check encoding with `file `. Convert with `iconv -f UTF-16LE -t UTF-8` and strip CR with `tr -d '\r'`. +Every repo should have a `.gitattributes` with `* text=auto eol=lf`. Files exported from Windows tools (SQL Server, Excel) arrive as UTF-16LE with CRLF; normalize to UTF-8 LF before committing. diff --git a/rules/MakefileFirst.md b/rules/MakefileFirst.md deleted file mode 100644 index f8bf839..0000000 --- a/rules/MakefileFirst.md +++ /dev/null @@ -1,3 +0,0 @@ -All module build, install, test, and lint logic runs through Makefiles. No standalone shell scripts that duplicate or bypass Make targets — they become invisible, untested, and unmaintainable. - -Modules include shared fragments from forge-lib (`mk/*.mk`) and override only what differs. A new module should need ~20 lines of Makefile, not 200. diff --git a/rules/MemoryFiles.md b/rules/MemoryFiles.md index 99f1f0b..5973b9d 100644 --- a/rules/MemoryFiles.md +++ b/rules/MemoryFiles.md @@ -1,3 +1,3 @@ -Never store learnings, feedback, or conventions in Claude Code's auto-memory (`~/.claude/projects/.../memory/`). All reusable knowledge belongs in the relevant module's `rules/` directory where it gets version-controlled, installed to `.claude/rules/`, and shared across sessions. +Reusable knowledge (conventions, corrections, pitfalls) graduates to a rule in the owning module's `rules/` directory, where it gets version-controlled, installed to every provider's rules tree, and stays visible across harnesses. A convention that lives only in one harness's auto-memory counts as unrecorded. If no module clearly owns it, use forge-steering. -Auto-memory is ephemeral, invisible to other tools, and truncated at 200 lines. Module rules are the source of truth. When you learn something that should persist (a correction, a convention, a pitfall), write a rule file in the owning module. If no module clearly owns it, use forge-steering. +Harness auto-memory (Claude Code's `~/.claude/projects//memory/`, Codex/Gemini/opencode equivalents) is a supplementary layer for session continuity, user context, and project state. It is never the system of record. diff --git a/rules/NoTabs.md b/rules/NoTabs.md index dec2c67..06aa7e6 100644 --- a/rules/NoTabs.md +++ b/rules/NoTabs.md @@ -1 +1 @@ -No tab characters in any file. If a tool inserts tabs, fix the tool. If a linter wants tabs, override the linter. +No tab characters in any file, except where the format requires them (e.g. Makefile recipes). If a tool inserts tabs, fix the tool. If a linter wants tabs, override the linter. diff --git a/rules/NoVendorLockIn.md b/rules/NoVendorLockIn.md new file mode 100644 index 0000000..a3b51cb --- /dev/null +++ b/rules/NoVendorLockIn.md @@ -0,0 +1,9 @@ +No AI vendor is a single point of failure: artifacts are authored once in canonical form and compiled per harness, so any vendor can fail, reprice, or be replaced without rewriting content. + +`forge install` performs the compilation: Markdown agents become each harness's native format (TOML for Codex, slugified Markdown for Gemini), standard tool names (`Read`, `Bash`, `Grep`) in `defaults.yaml` and agents are remapped to native equivalents (`read_file`, `run_shell_command`), and frontmatter, `@` companion references, and provenance markers are stripped from deployed files. + +Author only the canonical Markdown form with standard tool names. Never write harness-specific formats (TOML) or native tool names in the source repository. + +Assembly also rewrites provenance sidecars (`adopt/v1` becomes `assemble/v1` at deploy); the [ProvenanceAudit][ProvenanceAudit] skill covers the layering and audit procedures. + +[ProvenanceAudit]: skills/ProvenanceAudit/SKILL.md diff --git a/rules/ProvenanceVerification.md b/rules/ProvenanceVerification.md deleted file mode 100644 index 034ad8e..0000000 --- a/rules/ProvenanceVerification.md +++ /dev/null @@ -1,7 +0,0 @@ -`forge provenance` checks deployment integrity by reading `.provenance/` sidecar files (SLSA attestations) and comparing the recorded SHA-256 digest against the actual deployed file content. It reports per-module verification rates and flags files that were modified after deployment. - -```sh -forge provenance ~/.claude # check user-scope deployment -forge provenance .claude # check project-scope deployment -forge provenance ~/.claude --show-orphans # include files without provenance records -``` diff --git a/rules/RuleStructure.md b/rules/RuleStructure.md index 38bb23f..645343e 100644 --- a/rules/RuleStructure.md +++ b/rules/RuleStructure.md @@ -1,9 +1,9 @@ -A rule is a single `.md` file in `rules/`. Flat directory, no subdirectories except locale directories (`rules/cs-CZ/`). +A rule is a single `.md` file in `rules/`. The only valid subdirectories are locale directories (`rules/cs-CZ/`), harness and model qualifier directories (`rules/claude/`, `rules/claude/claude-opus-4-6/`), and gitignored `user/` overrides; see [PROV-0005](../docs/decisions/PROV-0005 Qualifier Directories for Model Targeting.md) for resolution precedence. -Frontmatter is optional. When present, it can carry `name`, `version`, `description`, and `targets` (provider filter). Assembly strips frontmatter before deployment. +Frontmatter is optional. When present, it can carry `name`, `version`, `description`, `targets` (harness filter), and `mode` (`replace` | `append` | `prepend`) on qualifier variants. Assembly strips frontmatter before deployment. -Body is the instruction — concise, actionable prose. No headings required. Max depth 3 if headings are used. +Body is the instruction: concise, actionable prose. No headings required. Max depth 3 if headings are used. -Rules are always loaded into the AI context for every session ([Claude Code docs][CCDOCS]). Keep them short — every word costs tokens on every interaction. +Rules are always loaded into the AI context for every session ([Claude Code docs][CCDOCS]). Keep them short; every word costs tokens on every interaction. [CCDOCS]: https://code.claude.com/docs/en/memory diff --git a/rules/ScanRepository.md b/rules/ScanRepository.md deleted file mode 100644 index 51bbe50..0000000 --- a/rules/ScanRepository.md +++ /dev/null @@ -1 +0,0 @@ -When reviewing code that touches repositories, base classes, or DI wiring -- read the actual source files before making claims. Diffs alone hide constructor signatures, class hierarchies, and service registration that determine whether a change is correct. diff --git a/rules/SecretScan.md b/rules/SecretScan.md deleted file mode 100644 index 87cb7dd..0000000 --- a/rules/SecretScan.md +++ /dev/null @@ -1,10 +0,0 @@ -Use `.gitleaks.toml` for path exclusions instead of `.gitleaksignore` fingerprints. Fingerprints break when line numbers shift. Path exclusions are stable: - -```toml -[allowlist] -paths = [ - "evals/baselines/.*", -] -``` - -Different gitleaks versions (apt vs homebrew vs GitHub Action) detect different patterns. If local scans pass but CI fails, the version mismatch is the likely cause. diff --git a/rules/SelfLearning.md b/rules/SelfLearning.md index e00de35..10acc7b 100644 --- a/rules/SelfLearning.md +++ b/rules/SelfLearning.md @@ -1,6 +1,6 @@ Invoke [LearnFrom][LEARNFROM] to capture transferable learnings whenever ANY of these fire during a session: -- A council teardown (DeveloperCouncil, HiringCouncil, ProductCouncil, ResearchCouncil, VaultCouncil, KnowledgeCouncil, DebateCouncil) +- Teardown of a council, agent team, workflow, or any other multi-agent run - A history rewrite touching 5+ commits (squash, force-push, rebase) - A skill, agent, or rule rename, move, or deletion - 3+ corrections from the user in a single topic (messages starting with `no`, `don't`, `actually`, `wait`, `stop`, `what are you doing`) @@ -9,4 +9,4 @@ Invoke [LearnFrom][LEARNFROM] to capture transferable learnings whenever ANY of [LearnFrom][LEARNFROM] scans the session, proposes updates to rules, skills, and agents, and presents each via AskUserQuestion with Capture / Adjust / Skip options. -[LEARNFROM]: skills/LearnFrom/SKILL.md +[LEARNFROM]: ../skills/LearnFrom/SKILL.md diff --git a/rules/UseForge.md b/rules/UseForge.md index cdd9bf1..dd29695 100644 --- a/rules/UseForge.md +++ b/rules/UseForge.md @@ -4,7 +4,7 @@ Assembly deploys only `.md` files. Non-markdown files (Python scripts, shell scr `forge install` deploys rules, skills, and agents, not hooks. Wire hooks manually into `~/.claude/settings.json` using absolute paths. Read the module's `hooks/hooks.json` for the full hook list and replace `${CLAUDE_PLUGIN_ROOT}` with the absolute path to your clone. -`--force` overwrites user-modified deployed files but does not re-assemble from source. Clear the build cache (`rm -rf build/`) before reinstalling if source changed since last assembly. +`forge install` re-assembles from source on every run; add `--force` to also overwrite user-modified deployed files. `--target ~` deploys to user scope (`~/.claude/`, `~/.codex/`, etc.). The flag sets the base directory for provider directories. `--target ~/.claude` is wrong — it nests `~/.claude/.claude/`. diff --git a/rules/UseRTK.md b/rules/UseRTK.md index d1bb30b..c65ddc7 100644 --- a/rules/UseRTK.md +++ b/rules/UseRTK.md @@ -1,6 +1,4 @@ --- targets: [claude, codex] --- -Always prefix shell commands with `rtk` (where rtk stands for **Rust Token Killer**: ) — hard requirement, not optional. RTK calls binaries directly and bypasses aliases. - -RTK does not support `-C ` — use `command git -C ` or absolute paths for submodule git operations. +Always prefix shell commands with `rtk` (Rust Token Killer: ): hard requirement, not optional. RTK calls binaries directly and bypasses aliases. diff --git a/rules/ValidationChain.md b/rules/ValidationChain.md deleted file mode 100644 index e0a58c3..0000000 --- a/rules/ValidationChain.md +++ /dev/null @@ -1,7 +0,0 @@ -Single validation path: `make validate` → `.githooks/pre-commit` → validation tool. - -The pre-commit hook is the canonical entry point. CI calls `make validate` which delegates to the hook. Never duplicate validation logic across Makefile recipes, CI workflow steps, and hook scripts. - -The preferred runner for both pre-commit and CI is [prek][PREK]. Systems without prek fall back to `forge validate .` or downloading validate.sh. - -[PREK]: https://github.com/j178/prek diff --git a/rules/WindowsConstraints.md b/rules/WindowsConstraints.md deleted file mode 100644 index 9a2d482..0000000 --- a/rules/WindowsConstraints.md +++ /dev/null @@ -1,3 +0,0 @@ -Claude Code on Windows requires Git for Windows, which provides Git Bash. Plugin hooks run in Git Bash, not PowerShell or cmd. Write hooks as standard bash scripts — they work cross-platform without `.cmd` or `.ps1` wrappers. - -Platform detection inside a hook when needed: `$OS == "Windows_NT"`. diff --git a/rules/claude/haiku/ExplicitToolUse.md b/rules/claude/claude-haiku-4-5/ExplicitToolUse.md similarity index 100% rename from rules/claude/haiku/ExplicitToolUse.md rename to rules/claude/claude-haiku-4-5/ExplicitToolUse.md diff --git a/rules/claude/haiku-4-5/ScopeAwareness.md b/rules/claude/claude-haiku-4-5/ScopeAwareness.md similarity index 100% rename from rules/claude/haiku-4-5/ScopeAwareness.md rename to rules/claude/claude-haiku-4-5/ScopeAwareness.md diff --git a/rules/claude/opus-4-5/ToolVerification.md b/rules/claude/claude-opus-4-5/ToolVerification.md similarity index 100% rename from rules/claude/opus-4-5/ToolVerification.md rename to rules/claude/claude-opus-4-5/ToolVerification.md diff --git a/rules/claude/opus-4-6/AvoidDuplication.md b/rules/claude/claude-opus-4-6/AvoidDuplication.md similarity index 100% rename from rules/claude/opus-4-6/AvoidDuplication.md rename to rules/claude/claude-opus-4-6/AvoidDuplication.md diff --git a/rules/claude/opus-4-6/ProportionalEffort.md b/rules/claude/claude-opus-4-6/ProportionalEffort.md similarity index 100% rename from rules/claude/opus-4-6/ProportionalEffort.md rename to rules/claude/claude-opus-4-6/ProportionalEffort.md diff --git a/rules/claude/claude-opus-4-7/BehavioralSteering.md b/rules/claude/claude-opus-4-7/BehavioralSteering.md new file mode 100644 index 0000000..225ef93 --- /dev/null +++ b/rules/claude/claude-opus-4-7/BehavioralSteering.md @@ -0,0 +1,23 @@ +These thoughts mean STOP — you're rationalizing a bad decision: + +| Thought | Reality | +| ---------------------------------------- | ---------------------------------------------------------------- | +| "This is just a small change" | Small changes have big blast radii. Verify before claiming done. | +| "I'll clean this up while I'm here" | Scope creep. Do what was asked, then stop. | +| "I know what this code does" | Read it. Memory lies. Verify before asserting. | +| "Tests aren't needed for this" | If it can break, it needs a test. | +| "Let me add error handling just in case" | Don't guard against scenarios that can't happen. | +| "I'll create a helper for this" | Three similar lines beat a premature abstraction. | +| "I'll write a function to do X" | Check if X already exists. Scaffold around it instead of reimplementing. | +| "The user probably wants me to also..." | Do what was asked. Ask before expanding. | +| "I can skip reading the file" | Read before claiming. Every shortcut is a future bug. | +| "Quick fix for now, investigate later" | Root cause first. Symptom fixes create new bugs. | +| "I'm confident it works" | Confidence is not evidence. Run the command. | +| "Propose the full framework, then trim" | First pass gets heavily cut. Start minimal; scope up on demand. | +| "I know how this tool or format works" | External-behavior claims need evidence. Read docs or say you're unsure. | +| "I'll design what should exist here" | Scan existing skills and modules first. New usually collides with old. | +| "This short message clearly means X" | Short messages are easy to misread. Re-read before acting on new work. | +| "More detail is safer than less" | Bloat is unsafe. Fewer structured points beat a longer response. | +| "I'll create a new task/branch/stash" | State entropy. Reuse state; cleanup beats accumulation. | +| "Batch the git rm with the Write" | Parallel tool rejections don't abort sibling calls. Create destination first; delete source only after it's verified. | +| "brew uninstall just removes metadata" | It removes the `.app` from `/Applications` too. Move it aside first, or `rm` the Caskroom directory directly. | diff --git a/rules/DeadVariables.md b/rules/claude/claude-opus-4-7/DeadVariables.md similarity index 100% rename from rules/DeadVariables.md rename to rules/claude/claude-opus-4-7/DeadVariables.md diff --git a/rules/NeverRefuseWork.md b/rules/claude/claude-opus-4-7/NeverRefuseWork.md similarity index 100% rename from rules/NeverRefuseWork.md rename to rules/claude/claude-opus-4-7/NeverRefuseWork.md diff --git a/rules/PrepareDataOutsideLoops.md b/rules/claude/claude-opus-4-7/PrepareDataOutsideLoops.md similarity index 100% rename from rules/PrepareDataOutsideLoops.md rename to rules/claude/claude-opus-4-7/PrepareDataOutsideLoops.md diff --git a/rules/claude/claude-opus-4-8/BehavioralSteering.md b/rules/claude/claude-opus-4-8/BehavioralSteering.md new file mode 100644 index 0000000..225ef93 --- /dev/null +++ b/rules/claude/claude-opus-4-8/BehavioralSteering.md @@ -0,0 +1,23 @@ +These thoughts mean STOP — you're rationalizing a bad decision: + +| Thought | Reality | +| ---------------------------------------- | ---------------------------------------------------------------- | +| "This is just a small change" | Small changes have big blast radii. Verify before claiming done. | +| "I'll clean this up while I'm here" | Scope creep. Do what was asked, then stop. | +| "I know what this code does" | Read it. Memory lies. Verify before asserting. | +| "Tests aren't needed for this" | If it can break, it needs a test. | +| "Let me add error handling just in case" | Don't guard against scenarios that can't happen. | +| "I'll create a helper for this" | Three similar lines beat a premature abstraction. | +| "I'll write a function to do X" | Check if X already exists. Scaffold around it instead of reimplementing. | +| "The user probably wants me to also..." | Do what was asked. Ask before expanding. | +| "I can skip reading the file" | Read before claiming. Every shortcut is a future bug. | +| "Quick fix for now, investigate later" | Root cause first. Symptom fixes create new bugs. | +| "I'm confident it works" | Confidence is not evidence. Run the command. | +| "Propose the full framework, then trim" | First pass gets heavily cut. Start minimal; scope up on demand. | +| "I know how this tool or format works" | External-behavior claims need evidence. Read docs or say you're unsure. | +| "I'll design what should exist here" | Scan existing skills and modules first. New usually collides with old. | +| "This short message clearly means X" | Short messages are easy to misread. Re-read before acting on new work. | +| "More detail is safer than less" | Bloat is unsafe. Fewer structured points beat a longer response. | +| "I'll create a new task/branch/stash" | State entropy. Reuse state; cleanup beats accumulation. | +| "Batch the git rm with the Write" | Parallel tool rejections don't abort sibling calls. Create destination first; delete source only after it's verified. | +| "brew uninstall just removes metadata" | It removes the `.app` from `/Applications` too. Move it aside first, or `rm` the Caskroom directory directly. | diff --git a/rules/claude/claude-opus-4-8/DeadVariables.md b/rules/claude/claude-opus-4-8/DeadVariables.md new file mode 100644 index 0000000..4a8aee4 --- /dev/null +++ b/rules/claude/claude-opus-4-8/DeadVariables.md @@ -0,0 +1 @@ +When generating code, verify each variable is read by something. A variable that is assigned but never consumed downstream is dead weight -- delete it before committing. diff --git a/rules/claude/claude-opus-4-8/NeverRefuseWork.md b/rules/claude/claude-opus-4-8/NeverRefuseWork.md new file mode 100644 index 0000000..7711f7c --- /dev/null +++ b/rules/claude/claude-opus-4-8/NeverRefuseWork.md @@ -0,0 +1 @@ +Never warn the user about context window size, token limits, or session length. Never suggest "starting a fresh session" or "continuing in the next session" as a way to avoid doing work. If asked to do something, do it. The user manages their own context budget. diff --git a/rules/claude/claude-opus-4-8/PrepareDataOutsideLoops.md b/rules/claude/claude-opus-4-8/PrepareDataOutsideLoops.md new file mode 100644 index 0000000..d96c88c --- /dev/null +++ b/rules/claude/claude-opus-4-8/PrepareDataOutsideLoops.md @@ -0,0 +1 @@ +If a value is the same on every loop iteration, compute it once before the loop and reference it inside. Cloning or reconstructing data inside a loop would create a full copy per iteration. diff --git a/rules/claude/sonnet-4-5/AssertiveFindings.md b/rules/claude/claude-sonnet-4-5/AssertiveFindings.md similarity index 100% rename from rules/claude/sonnet-4-5/AssertiveFindings.md rename to rules/claude/claude-sonnet-4-5/AssertiveFindings.md diff --git a/rules/claude/sonnet/ReviewDiscipline.md b/rules/claude/claude-sonnet-4-5/ReviewDiscipline.md similarity index 100% rename from rules/claude/sonnet/ReviewDiscipline.md rename to rules/claude/claude-sonnet-4-5/ReviewDiscipline.md diff --git a/rules/claude/sonnet-4-6/OutputDiscipline.md b/rules/claude/claude-sonnet-4-6/OutputDiscipline.md similarity index 100% rename from rules/claude/sonnet-4-6/OutputDiscipline.md rename to rules/claude/claude-sonnet-4-6/OutputDiscipline.md diff --git a/rules/claude/claude-sonnet-4-6/ReviewDiscipline.md b/rules/claude/claude-sonnet-4-6/ReviewDiscipline.md new file mode 100644 index 0000000..d7bb6e1 --- /dev/null +++ b/rules/claude/claude-sonnet-4-6/ReviewDiscipline.md @@ -0,0 +1,3 @@ +When reviewing code, report only findings you are confident about. Do not speculate about potential issues without reading the relevant source files first. If you cannot verify a claim, say so rather than presenting it as a finding. + +Limit initial findings to the top 3 issues by severity. Do not pad reviews with stylistic suggestions or hypothetical edge cases. diff --git a/rules/gemini/AgentStructure.md b/rules/gemini/AgentStructure.md deleted file mode 100644 index aeda99f..0000000 --- a/rules/gemini/AgentStructure.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -mode: append ---- - -**Gemini Specifics:** -Gemini CLI relies on a different security and tool paradigm than Claude. When authoring agents exclusively for Gemini: -- Do NOT include `mcpServers` in the frontmatter, as native MCP support is unavailable in Gemini CLI. -- `permissionMode` is currently ignored by Gemini CLI — permissions are governed by the tool access configuration in `defaults.yaml` (translated to the agent's `.toml` file). -- While you author using standard names (`Read`, `Bash`), the deployed agent in `.gemini/agents/` will use native Gemini tool names (`read_file`, `run_shell_command`) per [ArtifactComposition](../ArtifactComposition.md). - -[GEMINI-CLI]: https://github.com/google-gemini/gemini-cli "Gemini CLI" diff --git a/skills/AdoptArtifact/SKILL.md b/skills/AdoptArtifact/SKILL.md index 03b1979..ac4d8e0 100644 --- a/skills/AdoptArtifact/SKILL.md +++ b/skills/AdoptArtifact/SKILL.md @@ -41,17 +41,9 @@ Pick the destination module. If nothing fits, defer the adoption; do not create ### 3. Apply transforms -Transforms are named operations that will extract into their own skills as patterns stabilize. In v1 they run inline: +Apply the transform pack from [RefinePrompt](../RefinePrompt/SKILL.md): align, rescope, debrand, minimize, extract. Its decision table says when each applies. -| Transform | What it does | -| ---------- | ----------------------------------------------------------------------------------------------------------- | -| `align` | Rename to PascalCase; fix indent, fence language tags, heading depth; strip upstream frontmatter fields forge doesn't use | -| `rescope` | Add or tighten `allowed-tools` to the narrowest set the skill actually uses | -| `debrand` | Remove hardcoded vendor references (specific tool names, external services, "powered by X" language) | -| `minimize` | Collapse motivational or marketing prose while preserving directive content | -| `extract` | Move bulk reference material into `@`-included companion files so the always-loaded `SKILL.md` stays lean | - -Record which transforms were applied; it guides the commit message and is what future transform-skill dependencies will represent in the sidecar. +Record which transforms were applied; it guides the commit message, and the sidecar pins the RefinePrompt version that supplied them. ### 4. Add forge frontmatter @@ -71,11 +63,7 @@ The `upstream` field is a human-facing pointer without SHA ([PROV-0006](docs/dec ### 5. Write the artifact -Land at `skills//SKILL.md` in the destination module. Compute its SHA-256 after writing: - -```sh -shasum -a 256 skills//SKILL.md -``` +Land at `skills//SKILL.md` in the destination module. Compute its SHA-256 after writing. ### 6. Write the provenance sidecar @@ -103,6 +91,10 @@ provenance: uri: forge-core/skills/AdoptArtifact/SKILL.md digest: sha256: + - name: RefinePrompt + uri: forge-core/skills/RefinePrompt/SKILL.md + digest: + sha256: runDetails: builder: id: forge-cli @@ -123,5 +115,4 @@ One commit per adoption. Commit message carries the prose rationale — what was - Skills and agents are eligible for adoption; rules are not ([ARCH-0012](docs/decisions/ARCH-0012 Community Adoption Strategy.md)) - First-party forge skills take precedence on name conflicts; rename the adoption or reject it - Every adoption writes a provenance sidecar; an adoption without provenance is not an adoption -- Defer the adoption if no existing module is a natural home; do not create new modules for one skill - Recompute the adopted artifact's SHA-256 and sync it to the provenance sidecar after ANY post-adoption edit. The sidecar's `subject.digest.sha256` must match the current file content, not the initial adoption state diff --git a/skills/ArchitectureDecision/Example.md b/skills/ArchitectureDecision/Example.md deleted file mode 100644 index 77fe8f6..0000000 --- a/skills/ArchitectureDecision/Example.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Hybrid ADR Placement -description: Root for ecosystem-spanning decisions, per-module for internal decisions -type: adr -category: process -tags: - - adr - - process -status: accepted -created: 2026-03-02 -updated: 2026-03-02 -author: "@N4M3Z" -project: forge-core -related: [] -responsible: ["@N4M3Z"] -accountable: ["@N4M3Z"] -consulted: [] -informed: [] -upstream: [] ---- - -# Hybrid docs/decisions/ placement for forge ADRs - -## Context - -The forge ecosystem spans a root repo and independently clonable modules. Decisions range from ecosystem-wide conventions to module-internal choices. A single centralized directory conflates these scopes; purely per-module scatters ecosystem conventions across repositories. - -## Considered Options - -- Centralized root only — all ADRs in one place, modules link by reference -- Per-module only — each module owns its decisions, no root directory -- Hybrid — root for ecosystem-spanning, per-module for internal - -## Decision - -Chosen option: **Hybrid**, because it matches the existing layering model. Modules are independently deployable, so module-internal rationale belongs with the module. Ecosystem-spanning decisions belong at root where all modules can reference them. Numbering is per-scope — root and modules count independently. - -## Consequences - -- Scope is self-documenting from file location — `Modules/forge-tlp/docs/decisions/` vs `docs/decisions/` signals the audience -- No global sequence; cross-scope references use relative paths rather than bare numbers diff --git a/skills/ArchitectureDecision/SKILL.md b/skills/ArchitectureDecision/SKILL.md index 5e40ee1..a3b19a3 100644 --- a/skills/ArchitectureDecision/SKILL.md +++ b/skills/ArchitectureDecision/SKILL.md @@ -33,15 +33,6 @@ When modifying code in an area governed by an ADR, re-read the ADR and verify it @user/ContextKeeper.md -## Workflow Routing - -| Workflow | Trigger | Section | -| ------------ | --------------------------------------------------- | -------------------------------------- | -| **Find** | "list ADRs", "show decisions", "what did we decide" | [Find Workflow](#find-workflow) | -| **Create** | "create ADR", "new ADR", "write ADR" | [Create Workflow](#create-workflow) | -| **Validate** | "validate ADR", "check ADR", "lint ADR" | [Validate Workflow](#validate-workflow) | -| **Capture** | Post-compaction prompt, "capture ADRs from session" | [Capture Workflow](#capture-workflow) | - ## ADR Conventions ### Placement @@ -82,8 +73,6 @@ Never modify an accepted ADR's decision text. To revise, create a new ADR and ma | 0001 | Adopt Architecture Decision Records | accepted | 2026-03-02 | ``` - Extract title from frontmatter `title:` field, status and date from `status:` and `created:`. - 3. When asked about a specific topic, search ADR titles and content for relevant keywords. Read and summarize matching ADRs with: Context, Decision, Consequences, Status. --- @@ -104,7 +93,7 @@ Never modify an accepted ADR's decision text. To revise, create a new ADR and ma - **Contradiction**: reverses an existing decision — create with `accepted`, mark old `superseded`. - **Complementary**: genuinely different ground — proceed, add cross-references. -6. Use the `$ADR_TEMPLATE` (default `templates/structured-madr.md`). Fill in all frontmatter fields and body sections. Write to the ADR directory. +6. Use the `$ADR_TEMPLATE` (default `templates/forge-adr.md`). Fill in all frontmatter fields and body sections. Write to the ADR directory. 7. Set status to `proposed` unless the decision is already confirmed — then set `accepted`. @@ -116,7 +105,7 @@ Never modify an accepted ADR's decision text. To revise, create a new ADR and ma 1. If a file path was provided, validate that file. Otherwise, ask which ADR to validate or validate the entire ADR directory. -2. Run frontmatter schema validation against `$ADR_SCHEMA` (default `templates/structured-madr.json`). Use the first available tool: +2. Run frontmatter schema validation against `$ADR_SCHEMA` (default `templates/forge-adr.json`). Use the first available tool: a. `structured-madr` local checkout at `~/Data/Developer/zircote/structured-madr`: ```sh @@ -147,23 +136,21 @@ Never modify an accepted ADR's decision text. To revise, create a new ADR and ma Triggered post-compaction or by the user asking to capture decisions from the current session. -1. If ContextKeeper MCP is available, query `search_archive` for additional session context that may have been compressed away. - -2. Review the current conversation context for architectural decisions. Look for: technology choices, pattern adoptions, convention changes, structural refactors, trade-off evaluations with explicit reasoning. +1. Review the current conversation context for architectural decisions. Look for: technology choices, pattern adoptions, convention changes, structural refactors, trade-off evaluations with explicit reasoning. -3. For each identified decision, run the Create workflow. Set status to `accepted` if the decision was confirmed during the session, `proposed` if it was discussed but not finalized. +2. For each identified decision, run the Create workflow. Set status to `accepted` if the decision was confirmed during the session, `proposed` if it was discussed but not finalized. -4. If no architectural decisions are found, report that and exit. +3. If no architectural decisions are found, report that and exit. --- ## Constraints -- Never modify an accepted ADR's decision text — create a new ADR and mark old as superseded - `$ADR_DIRECTORY` must contain `$ADR_MDSCHEMA` when it exists — scaffold it if missing - Status must be set at creation — never leave it blank - Always search multiple common locations before concluding no ADRs exist - Include links to related ADRs when decisions are connected +- An ADR records the decision and its rationale, not implementation status. No transient or current-state prose ("currently", "we just enabled it on N repos", "verified on this repo", session counts, dates of execution). State the decision in the timeless present. Session status, verification results, and what-was-done-today belong in journals, commit messages, or the backlog — never the ADR. ## Sources diff --git a/skills/ArchitectureDecision/SchemaValidation.md b/skills/ArchitectureDecision/SchemaValidation.md index aca500c..b5b15cd 100644 --- a/skills/ArchitectureDecision/SchemaValidation.md +++ b/skills/ArchitectureDecision/SchemaValidation.md @@ -15,10 +15,10 @@ Use the fork of [structured-madr validator][FORK] — the upstream validator enf ### 1. structured-madr local checkout -Clone [structured-madr][MADR] to `~/Data/Developer/zircote/structured-madr` and use its npm validator: +Clone the [fork][FORK] to `~/Data/Developer/zircote/structured-madr` and use its npm validator: ```sh -git clone https://github.com/zircote/structured-madr.git ~/Data/Developer/zircote/structured-madr +git clone https://github.com/N4M3Z/structured-madr.git ~/Data/Developer/zircote/structured-madr cd ~/Data/Developer/zircote/structured-madr && npm ci ``` @@ -44,7 +44,7 @@ npx ajv validate -s templates/forge-adr.json -d docs/decisions/*.md ### 4. GitHub Action (CI) ```yaml -- uses: zircote/structured-madr@main +- uses: N4M3Z/structured-madr@main with: path: docs/decisions schema: templates/forge-adr.json diff --git a/skills/ArchitectureDecision/TemplateReference.md b/skills/ArchitectureDecision/TemplateReference.md index c2984dc..19076b7 100644 --- a/skills/ArchitectureDecision/TemplateReference.md +++ b/skills/ArchitectureDecision/TemplateReference.md @@ -22,8 +22,11 @@ Three template tiers, from minimal to full: ## Filename Convention Read `$ADR_PREFIX` (default: `number`): -- `number`: `NNNN Title Name.md` — next available four-digit number -- `date`: `YYYY-MM-DD Title Name.md` — today's date at creation + +- `number`: `NNNN Title Name.md`, the next available four-digit number +- `date`: `YYYY-MM-DD Title Name.md`, today's date at creation + +Repos that group decisions into prefix sections name files `PREFIX-NNNN Title Name.md` (forge-core: `CORE-`, `ARCH-`, `PROV-`, `MVPR-`, `NAME-`). Each section numbers independently; assign the next available number within the matching section. Prefixes are per-scope. Root and module directories count independently. @@ -42,11 +45,11 @@ Prefixes are per-scope. Root and module directories count independently. | `author` | yes | string | GitHub handle (e.g., `@N4M3Z`) | | `project` | yes | string | Repository name | | `related` | no | string array | Filenames of related ADRs | -| `responsible` | no | string array | RACI: who does the work | -| `accountable` | no | string array | RACI: who approves the decision | -| `consulted` | no | string array | RACI: whose input is sought | -| `informed` | no | string array | RACI: who is notified | -| `upstream` | no | string array | Rules promoted from this ADR, or provenance sources | +| `responsible` | yes | string array | RACI: who does the work | +| `accountable` | yes | string array | RACI: who approves the decision | +| `consulted` | yes | string array | RACI: whose input is sought | +| `informed` | yes | string array | RACI: who is notified | +| `upstream` | yes | string array | Rules promoted from this ADR, or provenance sources | ## Sections diff --git a/skills/ArchitectureDecision/user/ForgeADR.md b/skills/ArchitectureDecision/user/ForgeADR.md index 63220e6..738ad67 100644 --- a/skills/ArchitectureDecision/user/ForgeADR.md +++ b/skills/ArchitectureDecision/user/ForgeADR.md @@ -4,25 +4,6 @@ Forge ADRs use [structured-madr][1] as the base template, extended with `x-forge The default template is `templates/forge-adr.md`, validated by `templates/forge-adr.json`. Both are overridable via `$ADR_TEMPLATE` and `$ADR_SCHEMA`. -Multiple tiers exist for different contexts: - -| Tier | Template | Schema | Use case | -| ---------------- | ------------------------------ | -------------------------------- | ------------------------------ | -| Nygard minimal | `templates/adr.md` | — | Quick records, 10-20 lines | -| MADR light | `templates/madr.md` | — | Standard decisions | -| Forge ADR | `templates/forge-adr.md` | `templates/forge-adr.json` | Forge ecosystem (default) | -| structured-madr | `templates/structured-madr.md` | `templates/structured-madr.json` | Upstream-compatible shared repos | - -Forge ADR adds these fields beyond structured-madr: - -| Field | Type | Purpose | -| ------------- | ------------ | ----------------------------------------------------- | -| `responsible` | string array | RACI: who does the work | -| `accountable` | string array | RACI: who approves the decision | -| `consulted` | string array | RACI: whose input is sought | -| `informed` | string array | RACI: who is notified | -| `upstream` | string array | Rules promoted from this ADR, or provenance sources | - Templates use `${VARIABLE}` placeholders resolvable by `envsubst`, with `%%` comments for inline guidance ([CORE-0008][4]). [1]: https://github.com/zircote/structured-madr diff --git a/skills/BashConventions/BashPatterns.md b/skills/BashConventions/BashPatterns.md index d455d89..296ec45 100644 --- a/skills/BashConventions/BashPatterns.md +++ b/skills/BashConventions/BashPatterns.md @@ -1,61 +1,3 @@ -## Use this skill when - -- Writing or reviewing Bash scripts for automation, CI/CD, or ops -- Hardening shell scripts for safety and portability - -## Do not use this skill when - -- You need POSIX-only shell without Bash features -- The task requires a higher-level language for complex logic -- You need Windows-native scripting (PowerShell) - -## Instructions - -1. Define script inputs, outputs, and failure modes. -2. Apply strict mode and safe argument parsing. -3. Implement core logic with defensive patterns. -4. Add tests and linting with Bats and ShellCheck. - -## Safety - -- Treat input as untrusted; avoid eval and unsafe globbing. -- Prefer dry-run modes before destructive actions. - -## Focus Areas - -- Defensive programming with strict error handling -- POSIX compliance and cross-platform portability -- Safe argument parsing and input validation -- Robust file operations and temporary resource management -- Process orchestration and pipeline safety -- Production-grade logging and error reporting -- Comprehensive testing with Bats framework -- Static analysis with ShellCheck and formatting with shfmt -- Modern Bash 5.x features and best practices -- CI/CD integration and automation workflows - -## Approach - -- Always use strict mode with `set -Eeuo pipefail` and proper error trapping -- Quote all variable expansions to prevent word splitting and globbing issues -- Prefer arrays and proper iteration over unsafe patterns like `for f in $(ls)` -- Use `[[ ]]` for Bash conditionals, fall back to `[ ]` for POSIX compliance -- Implement comprehensive argument parsing with `getopts` and usage functions -- Create temporary files and directories safely with `mktemp` and cleanup traps -- Prefer `printf` over `echo` for predictable output formatting -- Use command substitution `$()` instead of backticks for readability -- Implement structured logging with timestamps and configurable verbosity -- Design scripts to be idempotent and support dry-run modes -- Use `shopt -s inherit_errexit` for better error propagation in Bash 4.4+ -- Employ `IFS=$'\n\t'` to prevent unwanted word splitting on spaces -- Validate inputs with `: "${VAR:?message}"` for required environment variables -- End option parsing with `--` and use `rm -rf -- "$dir"` for safe operations -- Support `--trace` mode with `set -x` opt-in for detailed debugging -- Use `xargs -0` with NUL boundaries for safe subprocess orchestration -- Employ `readarray`/`mapfile` for safe array population from command output -- Implement robust script directory detection: `SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"` -- Use NUL-safe patterns: `find -print0 | while IFS= read -r -d '' file; do ...; done` - ## Compatibility & Portability - Use `#!/usr/bin/env bash` shebang for portability across systems @@ -69,67 +11,6 @@ - Use built-in Bash features over external commands when possible for portability - Avoid bashisms when POSIX compliance is required, document when using Bash-specific features -## Readability & Maintainability - -- Use long-form options in scripts for clarity: `--verbose` instead of `-v` -- Employ consistent naming: snake_case for functions/variables, UPPER_CASE for constants -- Add section headers with comment blocks to organize related functions -- Keep functions under 50 lines; refactor larger functions into smaller components -- Group related functions together with descriptive section headers -- Use descriptive function names that explain purpose: `validate_input_file` not `check_file` -- Add inline comments for non-obvious logic, avoid stating the obvious -- Maintain consistent indentation (2 or 4 spaces, never tabs mixed with spaces) -- Place opening braces on same line for consistency: `function_name() {` -- Use blank lines to separate logical blocks within functions -- Document function parameters and return values in header comments -- Extract magic numbers and strings to named constants at top of script - -## Safety & Security Patterns - -- Declare constants with `readonly` to prevent accidental modification -- Use `local` keyword for all function variables to avoid polluting global scope -- Implement `timeout` for external commands: `timeout 30s curl ...` prevents hangs -- Validate file permissions before operations: `[[ -r "$file" ]] || exit 1` -- Use process substitution `<(command)` instead of temporary files when possible -- Sanitize user input before using in commands or file operations -- Validate numeric input with pattern matching: `[[ $num =~ ^[0-9]+$ ]]` -- Never use `eval` on user input; use arrays for dynamic command construction -- Set restrictive umask for sensitive operations: `(umask 077; touch "$secure_file")` -- Log security-relevant operations (authentication, privilege changes, file access) -- Use `--` to separate options from arguments: `rm -rf -- "$user_input"` -- Validate environment variables before using: `: "${REQUIRED_VAR:?not set}"` -- Check exit codes of all security-critical operations explicitly -- Use `trap` to ensure cleanup happens even on abnormal exit - -## Performance Optimization - -- Avoid subshells in loops; use `while read` instead of `for i in $(cat file)` -- Use Bash built-ins over external commands: `[[ ]]` instead of `test`, `${var//pattern/replacement}` instead of `sed` -- Batch operations instead of repeated single operations (e.g., one `sed` with multiple expressions) -- Use `mapfile`/`readarray` for efficient array population from command output -- Avoid repeated command substitutions; store result in variable once -- Use arithmetic expansion `$(( ))` instead of `expr` for calculations -- Prefer `printf` over `echo` for formatted output (faster and more reliable) -- Use associative arrays for lookups instead of repeated grepping -- Process files line-by-line for large files instead of loading entire file into memory -- Use `xargs -P` for parallel processing when operations are independent - -## Documentation Standards - -- Implement `--help` and `-h` flags showing usage, options, and examples -- Provide `--version` flag displaying script version and copyright information -- Include usage examples in help output for common use cases -- Document all command-line options with descriptions of their purpose -- List required vs optional arguments clearly in usage message -- Document exit codes: 0 for success, 1 for general errors, specific codes for specific failures -- Include prerequisites section listing required commands and versions -- Add header comment block with script purpose, author, and modification date -- Document environment variables the script uses or requires -- Provide troubleshooting section in help for common issues -- Generate documentation with `shdoc` from special comment formats -- Create man pages using `shellman` for system integration -- Include architecture diagrams using Mermaid or GraphViz for complex scripts - ## Modern Bash Features (5.x) - **Bash 5.0**: Associative array improvements, `${var@U}` uppercase conversion, `${var@L}` lowercase @@ -147,72 +28,13 @@ - **GitHub Actions**: Use `shellcheck-problem-matchers` for inline annotations - **Pre-commit hooks**: Configure `.pre-commit-config.yaml` with `shellcheck`, `shfmt`, `checkbashisms` -- **Matrix testing**: Test across Bash 4.4, 5.0, 5.1, 5.2 on Linux and macOS -- **Container testing**: Use official bash:5.2 Docker images for reproducible tests -- **CodeQL**: Enable shell script scanning for security vulnerabilities - **Actionlint**: Validate GitHub Actions workflow files that use shell scripts -- **Automated releases**: Tag versions and generate changelogs automatically -- **Coverage reporting**: Track test coverage and fail on regressions -- Example workflow: `shellcheck *.sh && shfmt -d *.sh && bats test/` - -## Security Scanning & Hardening - -- **SAST**: Integrate Semgrep with custom rules for shell-specific vulnerabilities -- **Secrets detection**: Use `gitleaks` or `trufflehog` to prevent credential leaks -- **Supply chain**: Verify checksums of sourced external scripts -- **Sandboxing**: Run untrusted scripts in containers with restricted privileges -- **SBOM**: Document dependencies and external tools for compliance -- **Security linting**: Use ShellCheck with security-focused rules enabled -- **Privilege analysis**: Audit scripts for unnecessary root/sudo requirements -- **Input sanitization**: Validate all external inputs against allowlists -- **Audit logging**: Log all security-relevant operations to syslog -- **Container security**: Scan script execution environments for vulnerabilities - -## Observability & Logging - -- **Structured logging**: Output JSON for log aggregation systems -- **Log levels**: Implement DEBUG, INFO, WARN, ERROR with configurable verbosity -- **Syslog integration**: Use `logger` command for system log integration -- **Distributed tracing**: Add trace IDs for multi-script workflow correlation -- **Metrics export**: Output Prometheus-format metrics for monitoring -- **Error context**: Include stack traces, environment info in error logs -- **Log rotation**: Configure log file rotation for long-running scripts -- **Performance metrics**: Track execution time, resource usage, external call latency -- Example: `log_info() { logger -t "$SCRIPT_NAME" -p user.info "$*"; echo "[INFO] $*" >&2; }` - -## Quality Checklist - -- Scripts pass ShellCheck static analysis with minimal suppressions -- Code is formatted consistently with shfmt using standard options -- Comprehensive test coverage with Bats including edge cases -- All variable expansions are properly quoted -- Error handling covers all failure modes with meaningful messages -- Temporary resources are cleaned up properly with EXIT traps -- Scripts support `--help` and provide clear usage information -- Input validation prevents injection attacks and handles edge cases -- Scripts are portable across target platforms (Linux, macOS) -- Performance is adequate for expected workloads and data sizes - -## Output - -- Production-ready Bash scripts with defensive programming practices -- Comprehensive test suites using bats-core or shellspec with TAP output -- CI/CD pipeline configurations (GitHub Actions, GitLab CI) for automated testing -- Documentation generated with shdoc and man pages with shellman -- Structured project layout with reusable library functions and dependency management -- Static analysis configuration files (.shellcheckrc, .shfmt.toml, .editorconfig) -- Performance benchmarks and profiling reports for critical workflows -- Security review with SAST, secrets scanning, and vulnerability reports -- Debugging utilities with trace modes, structured logging, and observability -- Migration guides for Bash 3→5 upgrades and legacy modernization -- Package distribution configurations (Homebrew formulas, deb/rpm specs) -- Container images for reproducible execution environments ## Essential Tools ### Static Analysis & Formatting - **ShellCheck**: Static analyzer with `enable=all` and `external-sources=true` configuration -- **shfmt**: Shell script formatter with standard config (`-i 2 -ci -bn -sr -kp`) +- **shfmt**: Shell script formatter with standard config (`-i 4 -ci -bn -sr -kp`) - **checkbashisms**: Detect bash-specific constructs for portability analysis - **Semgrep**: SAST with custom rules for shell-specific security issues - **CodeQL**: GitHub's security scanning for shell scripts @@ -236,56 +58,12 @@ - **gitleaks**: Secrets scanning to prevent credential leaks - **Makefile**: Automation for lint, format, test, and release workflows -## Common Pitfalls to Avoid - -- `for f in $(ls ...)` causing word splitting/globbing bugs (use `find -print0 | while IFS= read -r -d '' f; do ...; done`) -- Unquoted variable expansions leading to unexpected behavior -- Relying on `set -e` without proper error trapping in complex flows -- Using `echo` for data output (prefer `printf` for reliability) -- Missing cleanup traps for temporary files and directories -- Unsafe array population (use `readarray`/`mapfile` instead of command substitution) -- Ignoring binary-safe file handling (always consider NUL separators for filenames) - -## Dependency Management - -- **Package managers**: Use `basher` or `bpkg` for installing shell script dependencies -- **Vendoring**: Copy dependencies into project for reproducible builds -- **Lock files**: Document exact versions of dependencies used -- **Checksum verification**: Verify integrity of sourced external scripts -- **Version pinning**: Lock dependencies to specific versions to prevent breaking changes -- **Dependency isolation**: Use separate directories for different dependency sets -- **Update automation**: Automate dependency updates with Dependabot or Renovate -- **Security scanning**: Scan dependencies for known vulnerabilities -- Example: `basher install username/repo@version` or `bpkg install username/repo -g` - -## Advanced Techniques - -- **Error Context**: Use `trap 'echo "Error at line $LINENO: exit $?" >&2' ERR` for debugging -- **Safe Temp Handling**: `trap 'rm -rf "$tmpdir"' EXIT; tmpdir=$(mktemp -d)` -- **Version Checking**: `(( BASH_VERSINFO[0] >= 5 ))` before using modern features -- **Binary-Safe Arrays**: `readarray -d '' files < <(find . -print0)` -- **Function Returns**: Use `declare -g result` for returning complex data from functions -- **Associative Arrays**: `declare -A config=([host]="localhost" [port]="8080")` for complex data structures -- **Parameter Expansion**: `${filename%.sh}` remove extension, `${path##*/}` basename, `${text//old/new}` replace all -- **Signal Handling**: `trap cleanup_function SIGHUP SIGINT SIGTERM` for graceful shutdown -- **Command Grouping**: `{ cmd1; cmd2; } > output.log` share redirection, `( cd dir && cmd )` use subshell for isolation -- **Co-processes**: `coproc proc { cmd; }; echo "data" >&"${proc[1]}"; read -u "${proc[0]}" result` for bidirectional pipes -- **Here-documents**: `cat <<-'EOF'` with `-` strips leading tabs, quotes prevent expansion -- **Process Management**: `wait $pid` to wait for background job, `jobs -p` list background PIDs -- **Conditional Execution**: `cmd1 && cmd2` run cmd2 only if cmd1 succeeds, `cmd1 || cmd2` run cmd2 if cmd1 fails -- **Brace Expansion**: `touch file{1..10}.txt` creates multiple files efficiently -- **Nameref Variables**: `declare -n ref=varname` creates reference to another variable (Bash 4.3+) -- **Improved Error Trapping**: `set -Eeuo pipefail; shopt -s inherit_errexit` for comprehensive error handling -- **Parallel Execution**: `xargs -P $(nproc) -n 1 command` for parallel processing with CPU core count -- **Structured Output**: `jq -n --arg key "$value" '{key: $key}'` for JSON generation -- **Performance Profiling**: Use `time -v` for detailed resource usage or `TIMEFORMAT` for custom timing - ## References & Further Reading ### Style Guides & Best Practices - [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) - Comprehensive style guide covering quoting, arrays, and when to use shell - [Bash Pitfalls](https://mywiki.wooledge.org/BashPitfalls) - Catalog of common Bash mistakes and how to avoid them -- [Bash Hackers Wiki](https://wiki.bash-hackers.org/) - Comprehensive Bash documentation and advanced techniques +- [Bash Hackers Wiki](https://flokoe.github.io/bash-hackers-wiki/) - Comprehensive Bash documentation and advanced techniques - [Defensive BASH Programming](https://www.kfirlavi.com/blog/2012/11/14/defensive-bash-programming/) - Modern defensive programming patterns ### Tools & Frameworks @@ -297,7 +75,6 @@ - [shdoc](https://github.com/reconquest/shdoc) - Documentation generator for shell scripts ### Security & Advanced Topics -- [Bash Security Best Practices](https://github.com/carlospolop/PEASS-ng) - Security-focused shell script patterns - [Awesome Bash](https://github.com/awesome-lists/awesome-bash) - Curated list of Bash resources and tools - [Pure Bash Bible](https://github.com/dylanaraps/pure-bash-bible) - Collection of pure bash alternatives to external commands diff --git a/skills/Brainstorming/SKILL.md b/skills/Brainstorming/SKILL.md index ae46ac0..90bb38c 100644 --- a/skills/Brainstorming/SKILL.md +++ b/skills/Brainstorming/SKILL.md @@ -23,11 +23,7 @@ Every project goes through this process. "Simple" projects are where unexamined Ask one question at a time. Wait for the answer before asking the next. Bundling questions overwhelms and produces shallow answers. -Good questions uncover constraints the user hasn't stated: -- "Who will use this?" (audience shapes API design) -- "What happens when this fails?" (error handling strategy) -- "Does this need to work with X?" (integration constraints) -- "What's the simplest version that would be useful?" (scope discipline) +Good questions uncover constraints the user hasn't stated. ## Proposing Approaches @@ -49,14 +45,6 @@ Lead with your recommendation and explain why. | "I'll figure it out as I go" | That's exploration, not implementation. Explore, then design. | | "There's only one way to do this" | There are always trade-offs. Name them. | -## Constraints - -- Never start implementation before design approval — this is a hard gate -- Ask one question at a time, not batches -- Always propose at least two approaches with trade-offs -- Scale design detail to complexity — don't over-specify simple projects -- Hand off to DesignSpec or WritePlan, never directly to code - ## Sources - diff --git a/skills/BuildAgent/ClaudeAgent.md b/skills/BuildAgent/ClaudeAgent.md index 2cc25a4..290c3b2 100644 --- a/skills/BuildAgent/ClaudeAgent.md +++ b/skills/BuildAgent/ClaudeAgent.md @@ -4,27 +4,7 @@ How forge agents deploy to Claude Code. Following [ArtifactComposition](../../ru ## Deployed Format -Source (`agents/SecurityArchitect.md`): -```yaml ---- -name: SecurityArchitect -description: "Security policy architect — threat modeling..." -version: 0.3.0 ---- -``` - -Deployed (`~/.claude/agents/SecurityArchitect.md`): -```yaml ---- -name: SecurityArchitect -description: Security policy architect — threat modeling... -model: sonnet -tools: Read, Grep, Glob, Bash, WebSearch ---- -# synced-from: SecurityArchitect.md -``` - -The binary resolves `model` and `tools` from `defaults.yaml` and adds the `# synced-from:` provenance header. +Deployment passes agent frontmatter through unchanged: the deployed file carries `name` and `description`. `model` and `tools` stay in `defaults.yaml` and are never written into the agent file. Provenance is recorded in a `.provenance/` sidecar directory next to the deployed agents. ## Model Resolution diff --git a/skills/BuildAgent/GeminiAgent.md b/skills/BuildAgent/GeminiAgent.md index 6d63eb6..0919a1c 100644 --- a/skills/BuildAgent/GeminiAgent.md +++ b/skills/BuildAgent/GeminiAgent.md @@ -4,9 +4,9 @@ When scaffolding agents for Gemini CLI, author them exactly the same way as Clau ## Deployment Translation -The `forge install` command (via `forge-cli`) handles the translation to Gemini's expected format. Following [ArtifactComposition](../../rules/ArtifactComposition.md), the build system performs: +The `forge install` command (via `forge-cli`) handles the translation to Gemini's expected format. Following [NoVendorLockIn](../../rules/NoVendorLockIn.md), the build system performs: -1. **Format Conversion**: Converts the `.md` file with frontmatter into the `.toml` format expected in `.gemini/agents/`. +1. **Name Slugification**: Deploys the `.md` file under a slugified filename (`DataAnalyst.md` becomes `data-analyst.md`) into `.gemini/agents/`. 2. **Tool Mapping**: Translates standard tool names used in `defaults.yaml` to their Gemini-native equivalents. ### Tool Mapping Reference @@ -20,8 +20,6 @@ The `forge install` command (via `forge-cli`) handles the translation to Gemini' | `Write` | `write_file` | | `Edit` | `replace` | -*(Note: Updating `forge-cli` to handle this automatic tool remapping is a separate required task).* - Authors should NOT manually use Gemini tool names in `defaults.yaml` or write raw `.toml` files in the source repository. Keep the source repository platform-agnostic. [GEMINI-CLI]: https://github.com/google-gemini/gemini-cli "Gemini CLI" \ No newline at end of file diff --git a/skills/BuildAgent/SKILL.md b/skills/BuildAgent/SKILL.md index de7091e..c31767f 100644 --- a/skills/BuildAgent/SKILL.md +++ b/skills/BuildAgent/SKILL.md @@ -43,7 +43,7 @@ Rules: | `agents/` | Module agents (shipped with the module) | | User vault workspace | Personal agents | -Agent `name` must be **unique across all locations** -- sync overwrites by name. +An agent is a single `.md` file in `agents/`: flat directory, no subdirectories. Agent `name` must be **unique across all locations** -- sync overwrites by name. ### Module Agent Frontmatter @@ -65,6 +65,10 @@ version: 0.1.0 | `description` | Yes | Pattern: `"Role -- capabilities. USE WHEN triggers."` | | `version` | Yes | Semantic version | +For council/team agents, include a scope note in `description`. + +Claude Code accepts additional frontmatter fields for personal agents (`model`, `tools`, `disallowedTools`, `permissionMode`, `maxTurns`, `effort`, `skills`, `memory`, `isolation`, `color`, `hooks`, `mcpServers`; see Sources). Module agents keep deployment config in `defaults.yaml`. + Model and tool assignments live in `defaults.yaml` (map format, keyed by agent name): ```yaml @@ -156,11 +160,9 @@ forge install --scope user # user-level install | Codex | `.toml` | TOML config in `.codex/config.toml`, agent prompt in `.codex/agents/` | | OpenCode | `.md` | Same format as Claude | -Deployment adds a `# synced-from: OriginalFilename.md` header for provenance tracking. Tool mapping to provider equivalents happens automatically. - -**Critical**: `forge install` reads provider keys from the `providers:` section in defaults.yaml to determine deployment targets. If a provider is missing from `providers:`, agents will not deploy there. +Tool mapping to provider equivalents happens automatically. Provenance is recorded in `.provenance/` sidecar directories next to the deployed files, and a `.manifest` dotfile at the target root tracks deployment state. -**User-created detection**: If an agent file already exists in the target directory without a `# synced-from:` header, `forge install` skips it to avoid overwriting user-created agents. When migrating from a committed provider dir to `agents/` source: delete the old file from disk first, then run `make install`. +After creating or modifying an agent, redeploy to pick up changes. --- @@ -177,28 +179,17 @@ Determine: If unclear, ask using AskUserQuestion. -### Step 2: Choose the location - -| Scenario | Location | -|-------------------------|-----------------------| -| Part of a forge module | `agents/AgentName.md` | -| Personal agent | User vault workspace | - -### Step 3: Check for naming conflicts - -The name must be unique across all source directories. +### Step 2: Write the agent file -### Step 4: Write the agent file +Write `agents/AgentName.md` following [Agent Conventions](#agent-conventions). -Follow the frontmatter and body structure from [Agent Conventions](#agent-conventions). - -### Step 5: Deploy +### Step 3: Deploy ```bash make install ``` -### Step 6: Verify +### Step 4: Verify The agent will be available as a `subagent_type` after restarting the session. @@ -206,9 +197,7 @@ The agent will be available as a `subagent_type` after restarting the session. ## Validate Workflow -### Step 1: Read the agent file - -### Step 2: Check frontmatter +### Step 1: Check frontmatter - [ ] `name` present and uses PascalCase - [ ] `name` has no spaces, hyphens, or abbreviations @@ -216,7 +205,7 @@ The agent will be available as a `subagent_type` after restarting the session. - [ ] `description` follows pattern: `"Role -- capabilities. USE WHEN triggers."` - [ ] `version` present -### Step 3: Check body structure +### Step 2: Check body structure - [ ] Starts with blockquote summary (`> ...`) - [ ] Has Role section (2-3 sentences) @@ -228,7 +217,7 @@ The agent will be available as a `subagent_type` after restarting the session. - [ ] No real PII in examples - [ ] Total length is 50-80 lines -### Step 4: Report +### Step 3: Report **COMPLIANT** or **NON-COMPLIANT** with specific issues and fixes. @@ -264,15 +253,6 @@ Total agents, compliant count, issues found, recommended fixes. --- -## Constraints - -- Never create an agent without `name` in frontmatter -- Always use PascalCase for agent names -- non-negotiable -- Model and tool config belongs in defaults.yaml, not agent frontmatter -- Agent descriptions must follow pattern: `"Role -- capabilities. USE WHEN triggers."` -- For council/team agents, include scope note in description -- After creating or modifying agents, deploy to see changes - ## Sources - diff --git a/skills/BuildHook/SKILL.md b/skills/BuildHook/SKILL.md index 849ec21..324f254 100644 --- a/skills/BuildHook/SKILL.md +++ b/skills/BuildHook/SKILL.md @@ -17,6 +17,10 @@ Create and validate hook scripts for forge modules. Hooks are bash scripts trigg ## Hook Conventions +### Design Principles + +Hooks must block or inject, never advise. A hook that "reminds" or "nudges" is a rule or skill in disguise. Before proposing a hook, check whether Claude Code already injects this context: rules are always loaded, skills are auto-discovered; don't duplicate what the runtime provides. Kill test: if a hook breaks silently and nobody notices for a month, it wasn't worth shipping. See [ARCH-0011](../../docs/decisions/ARCH-0011 Hook Design Principles.md) for the full design criteria. + ### Events and Output Modes Every hook handles one of 9 Claude Code events. Each event has a fixed output mode that determines how module output is handled: @@ -79,6 +83,10 @@ Claude Code pipes a JSON payload to hook scripts on stdin. The schema varies by Read stdin once: `INPUT=$(cat)`. Parse with `yq -p json` or a compiled binary. +### Windows + +Claude Code on Windows requires Git for Windows, which provides Git Bash. Plugin hooks run in Git Bash, not PowerShell or cmd. Write hooks as standard bash scripts; they work cross-platform without `.cmd` or `.ps1` wrappers. Platform detection inside a hook when needed: `$OS == "Windows_NT"`. + ### Registration Chain For dispatch to find a hook: @@ -89,15 +97,19 @@ For dispatch to find a hook: The 3-tier event check: `config.yaml` override (authoritative) > `module.yaml` events > hook file existence (fallback). -### Exit Code Conventions +### Exit Code and Output Contract + +Claude Code distinguishes three exit classes ([hooks reference][CCHOOKS]): exit 0 (success; stdout is parsed for JSON control fields), exit 2 (blocking error; stdout is ignored, stderr is fed back, and whether it blocks depends on the event), and any other code (non-blocking error; the action proceeds). The trap: `exit 1` blocks nothing despite being the conventional Unix failure code. + +Forge hooks block via exit 0 plus stdout JSON rather than exit 2: a structured decision carries its reason through the documented protocol and cannot be confused with an infrastructure failure. + +- Empty stdout = allow +- `{"decision":"block","reason":"..."}` = block +- `{"hookSpecificOutput":{"additionalContext":"..."}}` = context injection -| Mode | Exit 0 | Exit 2 | Other | -|-------------|---------|--------|-----------------------------| -| Gate | Allow | Block | Treated as allow | -| Concatenate | Success | N/A | Output included regardless | -| Passive | Success | N/A | Output discarded regardless | +Guard files use `$PPID` or `$SESSION_ID` scoping to prevent repeat firing within a session. Hooks that cannot build or run must exit 0 (graceful degradation: never block Claude on infrastructure failure). -Gate hooks that cannot build or run should exit 0 (graceful degradation — never block Claude on infrastructure failure). +[CCHOOKS]: https://code.claude.com/docs/en/hooks --- diff --git a/skills/BuildModule/CodexProvider.md b/skills/BuildModule/CodexProvider.md index 2c33056..6fcd83c 100644 --- a/skills/BuildModule/CodexProvider.md +++ b/skills/BuildModule/CodexProvider.md @@ -12,18 +12,6 @@ codex init Codex will not overwrite an existing `AGENTS.md`. -## Update - -To regenerate after changes, rename the existing file first, then diff: - -```bash -command mv AGENTS.md AGENTS.md.bak -codex init -diff AGENTS.md.bak AGENTS.md -``` - -Review the diff. Keep manual additions from `.bak` that the generator missed. Remove the `.bak` when satisfied. - ## Agent Configuration Codex agents use TOML in `~/.codex/config.toml` or `.codex/config.toml`: @@ -42,7 +30,7 @@ Built-in roles: `default`, `worker`, `explorer`. Custom roles define `descriptio ## Skill Compatibility -Codex has no standalone skills format — instructions are embedded in `AGENTS.md` or agent config. Forge skills deploy as content within `AGENTS.md` via the Codex adapter (`Adapters/codex/install.sh`). +Codex has no standalone markdown skills format. `forge install` assembles each skill file into TOML (`name`, `description`, `developer_instructions`) under `build/codex/skills//` and deploys it to the `.codex` target directory. ## Constraints diff --git a/skills/BuildModule/GeminiProvider.md b/skills/BuildModule/GeminiProvider.md index 96aa5e4..9acc023 100644 --- a/skills/BuildModule/GeminiProvider.md +++ b/skills/BuildModule/GeminiProvider.md @@ -12,18 +12,6 @@ gemini init Gemini will not overwrite an existing `GEMINI.md`. -## Update - -To regenerate after changes, rename the existing file first, then diff: - -```bash -command mv GEMINI.md GEMINI.md.bak -gemini init -diff GEMINI.md.bak GEMINI.md -``` - -Review the diff. Keep manual additions from `.bak` that the generator missed. Remove the `.bak` when satisfied. - ## Configuration Gemini CLI uses `settings.json` for project config. The instruction filename is configurable: diff --git a/skills/BuildModule/InstallGuide.md b/skills/BuildModule/InstallGuide.md index 5462a59..ee0a2af 100644 --- a/skills/BuildModule/InstallGuide.md +++ b/skills/BuildModule/InstallGuide.md @@ -2,7 +2,7 @@ The Documentation section checks that INSTALL.md exists. This companion validates its content — does it actually guide an AI agent through installation on all supported platforms? -Reference standard: [forge-learn INSTALL.md](https://github.com/N4M3Z/forge-learn/blob/main/INSTALL.md). +Reference standard: [Mintlify install.md](https://github.com/mintlify/install-md), template at [forge-cli templates/init/INSTALL.md](https://github.com/N4M3Z/forge-cli/blob/main/templates/init/INSTALL.md). ## Per-Platform Reference @@ -26,35 +26,35 @@ Check in order: ## Scaffold -Report `SCAFFOLD — full validation deferred`, check only: +Report `SCAFFOLD: full validation deferred`, check only: -| Check | Pass criteria | -|-------|---------------| -| AI notice | First blockquote mentions "AI agents" | -| Planned section | `## Planned` heading has content below it | +| Check | Pass criteria | +|-----------------|---------------------------------------------------| +| Summary | H1 title with a blockquote summary directly below | +| Planned section | `## Planned` heading has content below it | ## Standard All checks required: -| Check | Pass criteria | -|-------|---------------| -| AI notice | First blockquote mentions "AI agents" | -| Requirements | `## Requirements` heading with numbered items | -| Build / Deploy | Heading matching `## .*(Build\|Deploy).*` with a code block | -| Platforms | `## Platforms` heading (optional — required for Full tier) | -| Configuration | `## Configuration` heading (optional) | +| Check | Pass criteria | +|-------------|----------------------------------------------------------------------| +| Summary | H1 title with a blockquote summary directly below | +| Autonomy | Opening prose instructs the agent to execute the steps autonomously | +| OBJECTIVE | `## OBJECTIVE` heading with a one-sentence goal | +| DONE WHEN | `## DONE WHEN` heading with a measurable success condition | +| TODO | `## TODO` heading with a checklist of 3-7 items | +| Steps | Step headings with shell commands in fenced code blocks | +| EXECUTE NOW | Closing line starts with `EXECUTE NOW` and restates DONE WHEN | ## Full -Standard checks plus cross-platform support: +Standard checks plus build tooling: -| Check | Pass criteria | -|-------|---------------| -| POSIX section | Code block with `bash` or `sh` fence under Build heading | -| PowerShell fallback | `powershell` code block or heading containing "PowerShell" / "Windows" | -| PowerShell content | PowerShell blocks contain `.exe` or `cargo build` (not POSIX pasted in) | -| Platforms | `## Platforms` heading with Windows mentioned in the section body | +| Check | Pass criteria | +|-------------------|---------------------------------------------------------------| +| Build step | Steps include a build command (`cargo build` or equivalent) | +| Platform coverage | Steps cover each OS in `platforms:` (or all three if absent) | ## Status Levels diff --git a/skills/BuildModule/LinuxPlatform.md b/skills/BuildModule/LinuxPlatform.md index a01ad66..016289d 100644 --- a/skills/BuildModule/LinuxPlatform.md +++ b/skills/BuildModule/LinuxPlatform.md @@ -11,5 +11,5 @@ ```bash make install -make verify +make validate ``` diff --git a/skills/BuildModule/ModuleStructure.md b/skills/BuildModule/ModuleStructure.md index 7854ded..5fb4e96 100644 --- a/skills/BuildModule/ModuleStructure.md +++ b/skills/BuildModule/ModuleStructure.md @@ -11,7 +11,7 @@ Invoke: `/BuildModule validate path/to/module` | `module.yaml` exists | Has `name`, `version`, `description` | | `.claude-plugin/plugin.json` exists | Has `name`, `version`, `description`, `skills` | | Version match | `module.yaml` version == `plugin.json` version | -| `Makefile` exists | Has `install`, `verify`, `test`, `lint`, `check`, `clean` targets | +| `Makefile` exists | Has `install`, `validate`, `clean` targets | | `forge` CLI available | `forge --version` succeeds, binary is on PATH | | `defaults.yaml` | Exists if module has configurable behaviour | | `LICENSE` exists | EUPL-1.2 license file present at module root | @@ -22,8 +22,7 @@ Invoke: `/BuildModule validate path/to/module` | Check | Pass criteria | |-----------------------------------|--------------------------------------------------------------------------------------| | `README.md` | Exists, not empty, has `## License` section | -| `INSTALL.md` | Exists, starts with `> **For AI agents**: This guide covers installation of [module].` | -| `VERIFY.md` | Exists, starts with `> **For AI agents**: Complete this checklist after installation.` | +| `INSTALL.md` | Exists, follows Mintlify install.md: H1 title, blockquote summary, OBJECTIVE, DONE WHEN | | `CLAUDE.md` | Exists (Claude Code project instructions) | | `AGENTS.md` | Exists (Codex/OpenCode project overview) | | `GEMINI.md` | Exists (Gemini CLI project context) | @@ -106,26 +105,20 @@ Cross-check directory contents against `defaults.yaml` registration: ## 9. Makefile Consistency -Cross-check Makefile targets against directory structure: +Cross-check Makefile targets against the minimal pattern: -| Check | Pass criteria | -|--------------------------------|--------------------------------------------------------------------------------| -| Agent plumbing (if `agents/`) | Makefile declares `AGENT_SRC`, includes `agents/install.mk` + `agents/verify.mk` | -| Skill plumbing (if `skills/`) | Makefile declares `SKILL_SRC`, includes `skills/install.mk` + `skills/verify.mk` | -| install target | Runs `forge install` which deploys agents if `agents/` exists | -| clean target | Includes `clean-agents` if `agents/` exists | -| verify target | Includes `verify-agents` if `agents/` exists | -| check target | Tests for `agents/` directory and `forge` binary if `agents/` exists | +| Check | Pass criteria | +|-----------------|----------------------------------------------------------------| +| install target | Activates `.githooks` and runs `forge install --target ~` | +| validate target | Delegates to `.githooks/pre-commit` (single validation path) | +| clean target | Removes `build/` | +| No roster vars | No `AGENTS`/`SKILLS` variables; `forge install` reads `defaults.yaml` | ## 10. Installation Guide @InstallGuide.md -## 11. Verification Guide - -@VerifyGuide.md - -## 12. Report +## 11. Report Output a summary table: @@ -142,7 +135,6 @@ Configuration PASS / FAIL (N issues) Roster Consistency PASS / FAIL (N issues) Makefile Consistency PASS / FAIL (N issues) Installation Guide PASS / WARN (N) / FAIL (N) [tier: Full|Standard|Scaffold] -Verification Guide PASS / WARN (N) / FAIL (N) [tier: Full|Standard|Scaffold] ``` List specific failures with file paths and remediation hints. diff --git a/skills/BuildModule/OpenCodeProvider.md b/skills/BuildModule/OpenCodeProvider.md index e4cf1f5..3141e99 100644 --- a/skills/BuildModule/OpenCodeProvider.md +++ b/skills/BuildModule/OpenCodeProvider.md @@ -12,18 +12,6 @@ opencode init OpenCode will not overwrite an existing `AGENTS.md`. It also falls back to reading `CLAUDE.md` if `AGENTS.md` is absent (disableable via env var). -## Update - -To regenerate after changes, rename the existing file first, then diff: - -```bash -command mv AGENTS.md AGENTS.md.bak -opencode init -diff AGENTS.md.bak AGENTS.md -``` - -Review the diff. Keep manual additions from `.bak` that the generator missed. Remove the `.bak` when satisfied. - ## Configuration OpenCode uses `opencode.json` (JSON/JSONC) at project root or `~/.config/opencode/opencode.json` global. Supports an `instructions` array with glob patterns for additional instruction files. @@ -49,4 +37,4 @@ OpenCode follows the [Agent Skills](https://agentskills.io) standard. Skills liv | `PreCompact` | `experimental.session.compacting` | Context injection via `output.context.push()` | | `PreToolUse` | No equivalent | Skills-only in OpenCode | -Modules with lifecycle hooks need a TypeScript plugin adapter at `.opencode/plugins/.ts`. See `Core/docs/OpenCodeModuleCompatibility.md` for the adapter template. +Modules with lifecycle hooks need a TypeScript plugin adapter at `.opencode/plugins/.ts`. diff --git a/skills/BuildModule/SKILL.md b/skills/BuildModule/SKILL.md index 6a2731c..7c05bb2 100644 --- a/skills/BuildModule/SKILL.md +++ b/skills/BuildModule/SKILL.md @@ -6,7 +6,7 @@ description: "Design, build, and validate forge modules. USE WHEN create module, # BuildModule -Guide for creating robust forge modules. Focuses on the three-layer concern architecture and ensures modules are portable across AI coding tools. +Guide for creating robust forge modules. Focuses on the three-layer concern architecture and ensures modules are portable across AI coding tools. Modules follow the [Agent Skills](https://agentskills.io) standard for cross-provider compatibility. ## Module Structure @@ -23,13 +23,12 @@ module-name/ bin/ Entry points or build scripts src/ Source code (typically Rust) .claude-plugin/ Claude Code plugin manifest - Makefile Multi-provider install/verify/test + Makefile install/validate/clean targets delegating to forge CLAUDE.md Project instructions for Claude Code (generated) AGENTS.md Project overview for Codex/OpenCode (generated) GEMINI.md Project context for Gemini CLI (generated) README.md Human-facing documentation - INSTALL.md Installation guide - VERIFY.md Post-installation checklist + INSTALL.md Agent-executable installation guide ``` Not all directories are required. A skills-only module (no hooks, no Rust) only needs: `skills/`, `module.yaml`, `defaults.yaml`, `.claude-plugin/plugin.json`, `Makefile`. @@ -42,7 +41,7 @@ Not all directories are required. A skills-only module (no hooks, no Rust) only 3. **Lazy Compilation**: Use `bin/_build.sh` to compile binaries on first hook invocation, ensuring low overhead. -4. **Validation Driven**: Always provide a `VERIFY.md` that allows an AI agent to confirm the module is functional without manual intervention. +4. **Validation Driven**: Ship an `INSTALL.md` following the [Mintlify install.md](https://github.com/mintlify/install-md) standard. Its DONE WHEN section embeds a measurable success condition so an AI agent can confirm the module is functional without manual intervention. ## Three-Layer Architecture @@ -99,17 +98,21 @@ agents: providers: claude: - fast: claude-sonnet-4-6 - strong: claude-opus-4-6 + models: + fast: [claude-sonnet-4-6] + strong: [claude-opus-4-6] gemini: - fast: gemini-2.0-flash - strong: gemini-2.5-pro + models: + fast: [gemini-2.0-flash] + strong: [gemini-2.5-pro] codex: - fast: o4-mini - strong: o4-mini + models: + fast: [gpt-5.3-codex] + strong: [gpt-5.4] opencode: - fast: claude-sonnet-4-6 - strong: claude-opus-4-6 + models: + fast: [claude-sonnet-4-6] + strong: [claude-opus-4-6] ``` The `skills:` section uses provider-keyed allowlists. `forge install` reads this to decide which skills deploy to which provider. Skills omitted from a provider's list are skipped. This allows Claude-only skills (e.g., those using agent teams) to be excluded from Gemini/Codex without per-skill configuration. @@ -132,34 +135,27 @@ Add `"hooks": "./hooks/hooks.json"` only if the module has hooks. ## Makefile Pattern -Modules use the `forge` CLI for install, verify, and validate targets: +All module build, install, test, and lint logic runs through Makefiles. No standalone shell scripts that duplicate or bypass Make targets; they become invisible, untested, and unmaintainable. + +Modules ship a minimal Makefile (~20 lines, not 200) that activates git hooks and delegates to the `forge` CLI: ```makefile -AGENTS = AgentName -SKILLS = SkillOne SkillTwo SkillThree -AGENT_SRC = agents -SKILL_SRC = skills +FORGE ?= forge -.PHONY: help install clean verify test lint check +.PHONY: help install validate clean install: - forge install - -clean: - forge clean + git config core.hooksPath .githooks + $(FORGE) install --target ~ -verify: - forge verify +validate: + @bash .githooks/pre-commit -test: - forge validate $(CURDIR) - -lint: lint-schema lint-shell +clean: + rm -rf build/ ``` -**SKILLS variable**: Lists skills for verification and cleanup only. `forge install` reads `defaults.yaml` directly to decide what deploys where. Provider-specific skills (e.g., Claude-only) should be excluded from the global SKILLS list since `verify` checks all providers. The skill will still install correctly via defaults.yaml. - -For skills-only modules (no agents), omit `AGENTS`, `AGENT_SRC`, and the agent mk includes. +`forge install` reads `defaults.yaml` directly to decide what deploys where, so the Makefile needs no agent or skill roster variables. ## Provider Documentation @@ -173,13 +169,23 @@ Every module ships platform-specific instruction files at its root: Generate these files by running each platform's CLI init command inside the module directory. The CLI analyzes the codebase and produces platform-appropriate instructions. To update an existing file, rename it to `.bak`, re-run init, and diff. -These files are the primary way AI agents understand the module when working inside it. Generate them after the module structure is complete and before first commit. +Generate them after the module structure is complete and before first commit. + +## Session Capture + +Once the module is a git repository — and before substantial agent work begins — enable [Entire](https://github.com/entireio/cli) so every coding session is checkpointed onto a commit-anchored branch from the start. Match `--agent` to the tool in use (`claude-code`, `codex`, `gemini`, `opencode`, and others): + +```bash +entire enable --agent --skip-push-sessions --local --telemetry=false +``` + +`--skip-push-sessions` keeps the transcript branch local-only, which is mandatory for a public module: a default enable would publish the verbatim session transcript on `git push`. `--local` writes gitignored settings. See the SessionContinuity skill (forge-dev) for the resume, rewind, and review workflows. ## Validation Flow 1. **Unit Tests**: `cargo test` (or equivalent) for Rust modules -2. **Module Conventions**: `forge validate .` checks structure -3. **Skill Verification**: `make verify` confirms deployment +2. **Module Conventions**: `forge validate` checks structure +3. **Pre-commit Gate**: `make validate` runs `.githooks/pre-commit` 4. **Binary Availability**: Check binaries respond to `--help` or `--version` ## Validate diff --git a/skills/BuildModule/VERIFY.mdschema b/skills/BuildModule/VERIFY.mdschema deleted file mode 100644 index a8dcd1f..0000000 --- a/skills/BuildModule/VERIFY.mdschema +++ /dev/null @@ -1,18 +0,0 @@ -# VERIFY.md schema for forge modules - -heading_rules: - no_skip_levels: true - max_depth: 3 - -structure: - - heading: '# Verify' - allow_additional: true - children: - - heading: '## Health check' - - heading: '## Structure validation' - optional: true - - heading: '## Functionality tests' - optional: true - - heading: '## Success criteria' - - heading: '## Troubleshooting' - optional: true diff --git a/skills/BuildModule/VerifyGuide.md b/skills/BuildModule/VerifyGuide.md deleted file mode 100644 index f465694..0000000 --- a/skills/BuildModule/VerifyGuide.md +++ /dev/null @@ -1,41 +0,0 @@ -# Verification Guide Validation - -The Documentation section checks that VERIFY.md exists. This companion validates its content — does it actually confirm the module works after installation? - -Reference standard: [forge-learn VERIFY.md](https://github.com/N4M3Z/forge-learn/blob/main/VERIFY.md). - -## Tier Detection - -Same tier as INSTALL.md (Scaffold / Standard / Full). See @InstallGuide.md for detection logic. - -## Scaffold - -| Check | Pass criteria | -|-------|---------------| -| AI notice | First line is blockquote or paragraph mentioning "AI agents" | -| Health check | Has at least one check with a bash code block | - -## Standard - -| Check | Pass criteria | -|-------|---------------| -| AI notice | First line is blockquote or paragraph mentioning "AI agents" | -| Health check | `## Health check` heading with quick verification commands | -| Structure validation | `## Structure validation` heading verifying expected files (optional) | -| Success criteria | `## Success criteria` heading summarizing pass/fail | - -## Full - -Standard checks plus: - -| Check | Pass criteria | -|-------|---------------| -| Health check | Includes binary availability checks (`--version` / `--help`) | -| Functionality tests | `## Functionality tests` heading with at least one functional test | -| Test suite | `cargo test` command with expected test count | - -## Status Levels - -- **FAIL** — required check missing (heading absent) -- **WARN** — heading present but content insufficient -- **PASS** — all checks pass for the detected tier diff --git a/skills/BuildModule/WindowsPlatform.md b/skills/BuildModule/WindowsPlatform.md index 75ba840..0c1a552 100644 --- a/skills/BuildModule/WindowsPlatform.md +++ b/skills/BuildModule/WindowsPlatform.md @@ -15,9 +15,9 @@ If staying in PowerShell: ```powershell $env:PATH = "$env:USERPROFILE\.cargo\bin;$env:PATH" -forge install --provider claude --scope workspace -forge install --provider codex --scope workspace -forge install --provider opencode --scope workspace +forge install --provider claude +forge install --provider codex +forge install --provider opencode ``` ## Notes diff --git a/skills/BuildModule/macOSPlatform.md b/skills/BuildModule/macOSPlatform.md index f450a20..3930fa1 100644 --- a/skills/BuildModule/macOSPlatform.md +++ b/skills/BuildModule/macOSPlatform.md @@ -11,5 +11,5 @@ ```bash make install -make verify +make validate ``` diff --git a/skills/BuildPlugin/ClaudeMarketplace.md b/skills/BuildPlugin/ClaudeMarketplace.md index 247d0ca..af0f65c 100644 --- a/skills/BuildPlugin/ClaudeMarketplace.md +++ b/skills/BuildPlugin/ClaudeMarketplace.md @@ -10,6 +10,14 @@ A marketplace is a GitHub repo with `.claude-plugin/marketplace.json` at the roo **Cowork** (organizational plugin management) clones the marketplace repo with plain `git clone`. It does not run `--recursive` or resolve remote source URLs. Only plugins physically present as directories inside the marketplace repo are visible to Cowork. Submodules resolve to empty directories and fail silently. +### Cowork Hook Limitation + +Cowork silently drops all plugin hooks. The CLI is spawned with `--setting-sources user`, which excludes plugin-scoped hook discovery ([GitHub #27398][ISSUE]). All hook types (command, prompt, agent) are affected, and no error is surfaced. Skills, agents, and MCP servers work in Cowork. + +Any behavior that must work in Cowork cannot rely on hooks. Ship it as a rule (always loaded) or a skill (user-invoked) instead. + +[ISSUE]: https://github.com/anthropics/claude-code/issues/27398 + ### Prerequisites - Module passes BuildPlugin validation @@ -55,20 +63,7 @@ These source types work in the Claude Code CLI but are not visible to Cowork: ### Plugin Auto-Discovery -Claude Code auto-discovers these directories from a plugin: - -| Directory | Loaded when | -| ---------------- | -------------------------------------- | -| `skills/` | User invokes or Claude matches | -| `agents/` | User selects or Claude delegates | -| `hooks/` | Event fires (SessionStart, PreToolUse) | -| `commands/` | Legacy name for skills | -| `output-styles/` | Output formatting | -| `.mcp.json` | MCP server definitions | -| `.lsp.json` | LSP server definitions | -| `settings.json` | Default agent settings | - -**Not discovered: `rules/`, `CLAUDE.md`, `memory/`.** These only load from project-level (`.claude/`) and user-level (`~/.claude/`) paths. See PluginContextInjection rule for the workaround. +Auto-discovered directories, the `rules/` gap, and the SessionStart `additionalContext` workaround are covered by [ClaudePlugin.md](ClaudePlugin.md). ### Plugin Requirements @@ -94,7 +89,3 @@ Cannot use: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-of ### Verify Sync After pushing, trigger sync in Cowork: Settings > Plugins > Sync marketplace. The plugin should appear in the available plugins list. - -[COWORK]: https://support.claude.com/en/articles/13837433-manage-cowork-plugins-for-your-organization -[MARKETPLACE]: https://code.claude.com/docs/en/plugin-marketplaces -[PLUGINS-REF]: https://code.claude.com/docs/en/plugins-reference diff --git a/rules/ClaudePluginStructure.md b/skills/BuildPlugin/ClaudePlugin.md similarity index 85% rename from rules/ClaudePluginStructure.md rename to skills/BuildPlugin/ClaudePlugin.md index ee1fe29..78667ad 100644 --- a/rules/ClaudePluginStructure.md +++ b/skills/BuildPlugin/ClaudePlugin.md @@ -15,7 +15,7 @@ Auto-discovered directories from a plugin: Not discovered: `rules/`, `CLAUDE.md`, `memory/`. These only load from project-level (`.claude/`) and user-level (`~/.claude/`) paths. -`bin/` is flat — files directly inside are added to the Bash tool's PATH ([plugins reference][CCPLUGINS]). No subdirectory recursion. Use extensionless names with shebangs and `chmod +x`. +`bin/` is flat: files directly inside are added to the Bash tool's PATH ([plugins reference][CCPLUGINS]). No subdirectory recursion. Use extensionless names with shebangs and `chmod +x`. Environment variables available in hook commands and subprocesses: @@ -30,7 +30,7 @@ To deliver always-on domain knowledge from a plugin, use a SessionStart hook tha {"hookSpecificOutput":{"additionalContext":"rule content here"}} ``` -Manifest at `.claude-plugin/plugin.json` — `name` (kebab-case) is the only required field. +Manifest at `.claude-plugin/plugin.json`: `name` (kebab-case) is the only required field. [CCPLUGINS]: https://code.claude.com/docs/en/plugins-reference [CCCREATE]: https://code.claude.com/docs/en/plugins diff --git a/skills/BuildPlugin/SKILL.md b/skills/BuildPlugin/SKILL.md index 07afbb9..6b4aecc 100644 --- a/skills/BuildPlugin/SKILL.md +++ b/skills/BuildPlugin/SKILL.md @@ -16,6 +16,7 @@ Create, validate, and publish forge modules as Claude Code plugins. Covers plugi | **Create** | "create plugin", "add plugin.json" | Instructions below | | **Validate** | "validate plugin", "check marketplace readiness" | Instructions below | | **Marketplace** | "add to marketplace", "publish to cowork" | @ClaudeMarketplace | +| **Structure** | "plugin layout", "auto-discovery", "bin PATH", "plugin env vars" | @ClaudePlugin | ## Create plugin.json @@ -74,8 +75,6 @@ Verdict: READY / NOT READY ## Constraints -- Plugin names must be lowercase kebab-case -- Version in plugin.json and module.yaml must match - Never publish a module that fails validation ## Sources diff --git a/skills/BuildSkill/PlatformAgnostic.md b/skills/BuildSkill/PlatformAgnostic.md index 5955aab..376ca87 100644 --- a/skills/BuildSkill/PlatformAgnostic.md +++ b/skills/BuildSkill/PlatformAgnostic.md @@ -3,3 +3,5 @@ Skills and agent definitions are instructions, not templates. Write them as plai Forbidden: `{{placeholders}}`, `[REPLACE THIS]`, ``, stub headings with no content, empty tables generated by a scaffold. If a section has nothing to say, delete it. Keep YAML frontmatter and `@` file includes — those are structural. But never reference skills with `/` prefix inside definitions. Use the skill name directly (e.g. "MemoryCapture", not "/MemoryCapture"). The slash is user-facing invocation syntax, not an internal identifier. + +A skill or agent that deploys to every provider must not assume one provider. Don't hardcode a single tool's agent identifier, CLI binary, or command syntax (`--agent claude-code`, `claude --resume`) when the artifact also runs under Codex, Gemini, or OpenCode. Parameterize the agent (`--agent `, listing the supported tools) and name actions neutrally ("the agent's resume command", not `claude --resume`). Documenting a tool's own factual default (a CLI flag that defaults to `claude-code`) is fine; that is the tool's behavior, not your assumption. diff --git a/skills/BuildSkill/SKILL.md b/skills/BuildSkill/SKILL.md index 75d91c7..c0fb386 100644 --- a/skills/BuildSkill/SKILL.md +++ b/skills/BuildSkill/SKILL.md @@ -23,6 +23,7 @@ Create and validate skills following forge conventions. Skills are markdown file | Multi-provider routing via `defaults.yaml` | [@MultiProviderRouting.md](MultiProviderRouting.md) | | Wrapping a CLI tool in a skill | [@CliToolIntegration.md](CliToolIntegration.md) | | Platform-agnostic writing — no placeholders or `/` prefix | [@PlatformAgnostic.md](PlatformAgnostic.md) | +| User-config schema for AI-first artifacts (autoMode mirror) | [@UserConfigSchema.md](UserConfigSchema.md) | | When to author a per-skill INSTALL.md | [@SkillInstallation.md](SkillInstallation.md) | ## Red Flags diff --git a/skills/ExecutePlan/SKILL.md b/skills/ExecutePlan/SKILL.md index 160efce..03efe25 100644 --- a/skills/ExecutePlan/SKILL.md +++ b/skills/ExecutePlan/SKILL.md @@ -21,17 +21,6 @@ Execute a WritePlan output in the current session, one task at a time. This is t 6. **Final verification** — after all tasks, run the full build + test suite 7. **Report** — summarize what was done, what was skipped, what needs follow-up -## Red Flags - -| Thought | Reality | -| ------------------------------------------------- | ------------------------------------------------------------ | -| "I'll do tasks 3 and 4 together, they're related" | One task at a time. Verify each before moving on. | -| "This task is wrong, let me improvise" | Stop. Fix the plan or ask the user. Don't freelance. | -| "I can skip verification on this one" | No. VerifyCompletion on every task. | -| "I'm blocked but I can probably work around it" | Stop and ask. Workarounds create hidden dependencies. | -| "Let me also fix this while I'm here" | Scope creep. Do what the plan says, nothing more. | -| "The plan is mostly done, close enough" | Partially executed plans are worse than unstarted ones. | - ## Constraints - One task at a time — never batch or skip ahead diff --git a/skills/GuardRails/SKILL.md b/skills/GuardRails/SKILL.md index adef717..dd3a75c 100644 --- a/skills/GuardRails/SKILL.md +++ b/skills/GuardRails/SKILL.md @@ -11,8 +11,7 @@ Two related disciplines under one roof: making sure execution doesn't go wrong a ## Companions -- [SafetyOverride.md](SafetyOverride.md) — operating under AI-safety plugins that gate destructive commands; how to recognize blocks and recover. -- [SafetyNet.md](SafetyNet.md) — reference for [claude-code-safety-net](https://github.com/kenryu42/claude-code-safety-net): rules, workarounds, when not to disable. +- [DestructiveCommandGuard.md](DestructiveCommandGuard.md) — reference for [dcg](https://github.com/Dicklesworthstone/destructive_command_guard): rules, workarounds, when not to disable. - [SecurityReview.md](SecurityReview.md) — per-language security review (python, javascript/typescript, go); secure-by-default coding, passive detection, full vulnerability reports. Future safety plugins land as sibling companions following the same shape: overview, what they catch, workarounds, configuration, when not to disable. @@ -21,9 +20,9 @@ Future safety plugins land as sibling companions following the same shape: overv | Trigger | Read | | ------------------------------------------------------------- | ----------------------------------- | -| A command just got blocked with a safety-plugin error | The plugin's companion (`SafetyNet.md` and similar) | +| A command just got blocked with a safety-plugin error | The plugin's companion (`DestructiveCommandGuard.md` and similar) | | Configuring a safety plugin for the first time | The plugin's companion | -| Considering whether to disable or override a rule | `SafetyOverride.md` | +| Considering whether to disable or override a rule | The plugin's § When not to disable | | User requests a security review of code | `SecurityReview.md` | | Starting a new project, want secure-by-default coding | `SecurityReview.md` | | Producing a vulnerability report | `SecurityReview.md` | @@ -32,5 +31,6 @@ Future safety plugins land as sibling companions following the same shape: overv - Never disable a safety plugin to push a blocked command through. - Never retry a blocked command with cosmetic variations to slip past the regex. +- When a block catches a genuine mistake, thank the guardrail and pick the safer path. - For irrecoverable operations (force-push to main, drop production table, unbounded `rm`), prefer hand-off to the user over attempting the command yourself. - Security review triggers only on explicit security-review requests, never on generic code review or debugging. diff --git a/skills/GuardRails/SafetyNet.md b/skills/GuardRails/SafetyNet.md deleted file mode 100644 index e9021fe..0000000 --- a/skills/GuardRails/SafetyNet.md +++ /dev/null @@ -1,56 +0,0 @@ -# SafetyNet - -The [claude-code-safety-net][SAFETY] plugin is a Claude Code hook that blocks destructive commands before they execute. Community plugin by kenryu42. Catches the common mistakes most likely to lose work permanently. - -## What it catches - -| Blocked | Why | -| ----------------------------------------- | ------------------------------------------------------------ | -| `rm -rf` outside cwd | Catastrophic data loss | -| `git reset --hard` | Discards committed and staged work | -| `git checkout -- ` | Discards uncommitted changes permanently | -| `find -delete` | Fire-and-forget mass delete | -| Force-push to main/master | Overwrites shared history | -| `git branch -D` | Force-delete branches (may lose unmerged commits) | -| `git checkout` with shell redirects | Redirects parsed as positional args (silent data loss) | - -## Workarounds when blocked - -| Blocked | Workaround | -| ----------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `rm -rf` outside cwd | `rm` specific files; `rm -r` scoped inside cwd; `find -print \| xargs rm -i` for controlled mass delete | -| `git reset --hard` | `git stash` the work first, then `git reset` (soft/mixed), then apply selectively | -| `git checkout -- ` | `git stash push [-u] -- ` — preserves changes in a recoverable stash; `git stash pop` restores | -| `find -delete` | `find ... -print \| xargs rm -i` for review, or explicit `rm` per file | -| Force-push to main | Merge via PR; never force-push protected branches | -| `git branch -D` | `git branch -d` for merged branches; hand unmerged deletes to the user | -| `git checkout` with redirects | Quote paths explicitly: `git checkout -- "file with spaces"` | - -## When blocked - -1. Read the safety-net error — it cites the regex that matched and the rationale. -2. Map to a workaround above. -3. If no workaround fits, hand the command back to the user to run manually. -4. Do not retry the same blocked command with cosmetic variations. - -## Configuration - -Safety-net ships with three user-invocable commands: - -- `/safety-net:set-custom-rules` — add user-specific blocks on top of the default ruleset. -- `/safety-net:verify-custom-rules` — inspect current custom rules and check they parse. -- `/safety-net:set-statusline` — toggle the statusline indicator showing the plugin is active. - -Custom rules live in Claude Code settings; see the plugin's README for the schema. - -## When not to disable - -- **Never** disable to push a command that just got blocked. The block is usually catching a real mistake. -- **Never** disable in shared sessions or CI — the guardrail is part of the trust contract with the user. -- **Consider** disabling only in scoped, transient contexts (e.g. a throwaway sandbox) where you genuinely need the blocked operation and accept full responsibility. - -## Sources - -- [Plugin repo][SAFETY] - -[SAFETY]: https://github.com/kenryu42/claude-code-safety-net diff --git a/skills/GuardRails/SafetyOverride.md b/skills/GuardRails/SafetyOverride.md deleted file mode 100644 index 64a31c6..0000000 --- a/skills/GuardRails/SafetyOverride.md +++ /dev/null @@ -1,16 +0,0 @@ -## SafetyOverride - -Operating safely when AI-safety plugins gate destructive commands. Each safety plugin in use is documented as a per-plugin companion (for example `SafetyNet.md`); this section covers the general decision discipline that applies to all of them. - -### When to consult this section - -1. A command just got blocked with a safety-plugin error. Look up the plugin's companion file for the mapped workaround. -2. Configuring a safety plugin for the first time. Custom rules, statusline, and so on. See the plugin's companion under § Configuration. -3. Deciding whether to disable or override a rule. Read § When not to disable in the plugin's companion before touching config. - -### Constraints - -- Never disable a safety plugin to push a blocked command through. -- Never retry the same blocked command with cosmetic variations to slip past the regex. -- When a block catches a genuine mistake, thank the guardrail and pick the safer path. -- For irrecoverable operations (force-push to main, drop production table, unbounded `rm`), prefer hand-off to the user over attempting the command yourself. diff --git a/skills/GuardRails/SecurityReview.md b/skills/GuardRails/SecurityReview.md index b777eed..7692fe8 100644 --- a/skills/GuardRails/SecurityReview.md +++ b/skills/GuardRails/SecurityReview.md @@ -4,13 +4,12 @@ Language and framework specific security best practices: secure-by-default codin ### Scope -Triggers only for python, javascript/typescript, and go. For other languages, rely on general knowledge and flag that concrete guidance is not available. +Primary coverage is python, javascript/typescript, and go. For other languages, perform the review from general security knowledge and flag that language-specific guidance is not available. ### Workflow 1. **Identify** the languages and frameworks in use; frontend and backend separately for web apps. Focus on the primary core frameworks. -2. **Load guidance**: if this skill's `references/` directory contains `---security.md` or a general `-general--security.md`, read all matching files. Web apps need both frontend and backend references. -3. **Operate in one of three modes**: +2. **Operate in one of three modes**: | Mode | Trigger | Behavior | | ----------------------- | ---------------------------------------- | ----------------------------------------------------------------- | @@ -18,8 +17,6 @@ Triggers only for python, javascript/typescript, and go. For other languages, re | Passively detect | Working in an existing project | Flag critical findings to the user inline | | Full report | User explicitly requests it | Write `security_best_practices_report.md` with prioritized issues | -If no references exist for the stack, note that concrete guidance is unavailable but still perform the action based on general security knowledge. - ### Overrides Project-level documentation may require bypassing specific best practices. When overriding, report the override to the user without arguing. Suggest adding a note to project docs explaining the reason so the bypass is visible to future work. @@ -49,9 +46,3 @@ Use UUID4 or random hex strings instead of small auto-incrementing integers. Pre #### TLS and secure cookies Do not report missing TLS as a security issue: dev environments rarely have TLS or use an out-of-scope proxy. Set `Secure` on cookies only when the app is actually over TLS; otherwise local dev and testing break. Provide an env flag to gate `Secure`. Avoid recommending HSTS: its lasting impact (including major user lockouts) requires deep understanding. - -### Constraints - -- Trigger only on explicit security-review requests, never on generic code review or debugging. -- Do not argue with project-level overrides; document them instead. -- Report dev-only TLS gaps as best-practice notes, not vulnerabilities. diff --git a/skills/HtmlPlayground/SKILL.md b/skills/HtmlPlayground/SKILL.md index 3c4700c..89c9b47 100644 --- a/skills/HtmlPlayground/SKILL.md +++ b/skills/HtmlPlayground/SKILL.md @@ -10,7 +10,7 @@ Generate a self-contained HTML file that renders techniques as side-by-side card ## When to use -Before adding CSS to a project (snippets, themes, component styles), render the candidates visually so the user can compare and choose. One HTML file, no dependencies, no build step. +Before adding CSS to a project (snippets, themes, component styles), render the candidates visually so the user can compare and choose. ## Instructions @@ -46,43 +46,9 @@ Each card is a self-contained demo. Use these conventions: - Demo content uses the same CSS variable names as the target platform (Obsidian vars for vault snippets, standard custom properties for web projects) - Mock data should feel real — use the user's actual project names, task descriptions, and entity types when known from conversation context -## HTML template skeleton - -```html - - - - - -{Topic} — CSS Preview - - - -

{Topic}

-

{Context line}

-
- -
- - -``` - ## Constraints - Maximum 6 cards per preview (4 techniques + 1 combined is ideal) -- All CSS inline in a single `