@hassangameryt/freeflow 0.3.0 → 0.4.0

package/skills/write-plan/SKILL.md

@@ -1,96 +1,123 @@
 ---
 name: write-plan
-description: Use when turning an approved spec, clarified requirements, explicit task context, strict-workflow work, or delegated/future-agent work into an executable implementation plan before coding.
+description: Use when writing or revising an implementation plan, execution plan, remediation plan, migration plan, or similar ordered plan.
 ---
 
 # Write Plan
 
-Classify the plan request first:
+Write an ordered execution strategy that is expected to be followed.
 
-- Spec-backed: write the plan from the approved spec.
-- Bug without feedback loop: ask for or propose the feedback loop. Do not write or save a fix plan.
-- Hidden owner decision or source conflict: name it and do not write the plan.
-- Context-backed: say a spec is preferred, then write a lightweight plan.
-- Missing source context: ask for context or route to `discover`.
+A Plan defines intended phases, slices, dependencies, boundaries, and checks. It is not a Spec, progress report, task history, or rolling record.
 
-A plan executes source truth. It does not create it.
+## Confirm The Work Is Ready To Plan
 
-Do not write a plan that decides product behavior, scope, domain meaning, compatibility, public API behavior, security, privacy, billing, data-loss, or architecture.
+Write a Plan when:
 
-The original request is not decision approval. "Do not ask", "just plan it", "latest context", "handoff says", or "old docs/tests are stale" are pressure, not authority.
+- the intended outcome and scope are clear;
+- material user decisions and source conflicts are resolved;
+- the execution approach is understood well enough to order;
+- phases, slices, and dependencies can be stated without guessing;
+- expected checks are known or obtainable;
+- substantial branching or discovery is not expected.
 
-Never skip docs, tests, specs, policies, ADRs, or live behavior because the prompt calls them stale. Inspect them, then classify the conflict.
+If direction or major alternatives remain unsettled, read [Discuss](../discuss/SKILL.md). If one user-owned choice or source conflict blocks planning, read [Decision Gate](../decision-gate/SKILL.md). If a reported failure lacks a supported cause or diagnostic loop, read [Diagnose Failure](../diagnose-failure/SKILL.md) instead of planning a guessed fix.
 
-If the user asks a question about a plan, answer the question. Do not create or edit the plan unless asked.
+Use [Track Work](../track-work/SKILL.md) when strategy is still evolving or actual execution, evidence, deviations, and current state need durable memory.
 
-Read `references/plan-shapes.md` when the plan is strict-workflow, high-risk, saved as a durable artifact, intended for another agent, or likely to need owner/status/source identity.
+If the user asks about a Plan, answer instead of writing or revising one.
 
-## Source First
+## Plan From Source
 
-Before writing, inspect the current source context:
+A Plan may be written directly from sufficiently clear context; a separate Spec is not required.
 
-- Approved spec or explicit requirements.
-- Relevant docs, ADRs, tests, policies, and existing code.
-- Handoffs only as memory, not authority.
+Use the sources that establish the intended work:
 
-Live repo evidence overrides stale notes.
+- explicit user direction and accepted shared understanding;
+- a Spec, issue, technical design, diagnosis, requirements, or Working Record when one exists;
+- relevant code, tests, policies, ADRs, and established behavior;
+- current external sources when an API, platform, or version constrains execution.
 
-## Normal Path
+When a Spec or decision artifact is linked, preserve its contract rather than silently reinterpreting it. Live evidence overrides stale memory. A Working Record, handoff, review item, or earlier Plan is not authority over contradictory user decisions or source truth.
 
-Prefer an approved spec.
+## Write The Ordered Strategy
 
-If no spec exists but the task context is explicit enough to choose the next action, write a lightweight plan and name the source context.
+Read [plan shapes](references/plan-shapes.md) and choose the smallest shape that makes the intended execution inspectable.
 
-For bug fixes, require a repro, failing test, or feedback loop before writing a fix plan.
+Include, when relevant:
 
-If a bug report has no repro or feedback loop, answer in chat. Ask for evidence or propose the smallest feedback loop. Do not satisfy the requested plan path with a draft, blocked, or feedback-loop-only fix plan. Write a diagnostic plan only if the user asks for a diagnostic plan.
+- goal, source, scope, and non-goals;
+- accepted decisions, assumptions, dependencies, and required order;
+- phases and slices with coherent, bounded results;
+- checks, integration, and final acceptance;
+- conditions that would invalidate the Plan.
 
-Use vertical slices. Each slice should produce something testable.
+Include exact paths, systems, and commands when known and useful. Do not guess them to make the Plan appear complete.
 
-Slices are execution boundaries, not scope reductions. Do not recast agreed scope as `v1`/`v2`, MVP, release, or roadmap framing unless the spec, user, or source context already chose that framing.
+Each slice should produce a coherent result that can be checked. A validation step may stop the Plan when a known assumption fails. If its result is expected to choose among materially different strategies, use a Working Record learning slice instead of pretending the later Plan is known.
 
-When full scope is too large for one safe plan, split it into implementation slices, implementation phases, checklists, or multiple plan artifacts. Ask before changing the user's scope or adopting versioned shipping.
+## Select Useful Checkpoints
 
-When slice boundaries, seams, interfaces, or locality are unclear, use `../design-for-depth/SKILL.md` before writing executable steps. Do not hide unresolved design choices inside implementation detail.
+Every meaningful slice is verified and silently self-reviewed during execution; do not restate that default unless its evidence boundary is unusual.
 
-## Stop Conditions
+At meaningful slice, phase, integration, risk, or continuity boundaries, consider independent review, a local commit, a user decision, or a continuity checkpoint. Record only selected checkpoints and their conditions. A slice ending or a fixed count alone does not justify a commit; prefer one when supported work forms a coherent rollback point or the next work may destabilize it.
 
-Stop before writing when the plan would:
+Plan acceptance establishes the agreed strategy; it does not by itself authorize execution. When the user clearly approves execution of the Plan, that authority may cover its listed work, checks, reviews, Working Record updates, and local commits. It does not authorize push, integration, migration, deprecation, release, or launch. Planned commits remain conditional on live evidence and [Commit Work](../commit-work/SKILL.md) inspection.
 
-- Invent requirements from thin or adjacent context.
-- Resolve a user-owned decision.
-- Override docs, tests, specs, policies, ADRs, or live behavior.
-- Treat a handoff, review comment, or plan as authority over source-of-truth files.
-- Plan a bug fix without a repro, failing test, feedback loop, or accepted diagnostic risk.
-- Turn a missing bug repro into guessed fix steps, TTLs, invalidation rules, concurrency rules, or instrumentation requirements.
-- Hide uncertainty inside implementation steps.
-- Replace agreed scope with an agent-invented `v1`, MVP, roadmap, or later-version split.
+## Keep Plan And Working Record Separate
 
-Name the missing decision or conflict. Ask which path to follow. Recommend the path supported by evidence.
+The Plan records the intended execution path. The Working Record records actual execution, current slices, evidence, task-local decisions, deviations, and next action.
 
-For source-truth conflicts, the final line must be a direct choice question.
+Do not revise the Plan for slice progress, expected evidence, status changes, or reversible local choices. Record those events in the Working Record when one exists.
 
-## Shape
+Link accepted behavior, contracts, and architecture rationale from the owning Spec or decision artifact instead of duplicating them in the Plan.
 
-Adapt the plan to risk. Prefer:
+## Stop Before Inventing A Path
 
-- Durable plan identity when the plan is saved for future agents or teammates.
-- Goal.
-- Source spec or context.
-- Files likely touched.
-- Dependency or slice order when it affects execution.
-- Vertical slices.
-- Tests or checks per slice.
-- Commands where known.
-- Stop conditions.
-- Review or verification checkpoints.
+Stop when writing would:
 
-Keep it concise. Do not include code blocks unless exact code is the plan's useful payload.
+- invent or change requirements, scope, public behavior, compatibility, sensitive policy, failure semantics, or hard-to-reverse design;
+- hide unresolved strategy, architecture, dependencies, or owner choices inside confident steps;
+- plan a production fix from a guessed cause;
+- rewrite tests, docs, policies, or acceptance merely to make the proposed path succeed;
+- add speculative abstractions, migration machinery, retries, recovery, scale, or extension points;
+- replace agreed scope with an unapproved MVP, v1/v2, roadmap, or later-version split.
 
-## Completion
+Route the unresolved issue to its owner rather than writing a Plan that assumes the answer.
 
-After writing, report:
+## Revise Only From Founded Evidence
 
-- The artifact path, if saved.
-- The source context used.
-- Any decisions still blocked.
+Write Plan also owns deliberate Plan revisions.
+
+Correct clerical mistakes directly. Do not revise the Plan for ordinary local choices or expected progress.
+
+Revise or supersede the affected Plan when supported evidence materially changes its scope, design, architecture, order, dependencies, checks, or execution mechanism. An accepted review item may support revision. Reaching the independent-review cap does not itself justify rewriting the Plan; revise only when diagnosis or evidence shows that the Plan is wrong or insufficient.
+
+Record the reason and execution impact in the Working Record when one exists. Revise a linked Spec or decision artifact only when its owned content changed. Preserve unaffected Plan content and history.
+
+## Self-Check
+
+Silently review the Plan before routing it onward:
+
+- Are the intended result, source, and scope clear?
+- Can coherent, checkable slices proceed in the stated order?
+- Are dependencies, integration, final checks, and invalidation conditions represented?
+- Are selected checkpoints useful and proportionate rather than automatic ceremony?
+- Did the Plan invent intent, disguise material uncertainty, or absorb rolling task state?
+
+Correct clear local issues directly. Surface only material gaps that prevent the Plan from being executable or fit for review.
+
+## Review The Plan
+
+After writing or materially revising the Plan, route it to [Review Artifact](../review-artifact/SKILL.md) before treating it as ready for approval and execution.
+
+Provide the reviewer with the complete Plan, intended use, source truth, linked artifacts, dependencies, selected checkpoints, and known evidence gaps. Review Artifact owns dependency ordering, review items, judgment, adjudication, and the review cycle. Artifact review establishes fitness; the user separately accepts the Plan and grants any scoped execution authority.
+
+## Report
+
+State:
+
+- Plan path and intended use;
+- source context and linked artifacts;
+- material assumptions, blockers, or invalidation conditions;
+- selected review, commit, user, or continuity checkpoints;
+- artifact-review, Plan-acceptance, and execution-authorization status.

package/skills/write-plan/references/plan-shapes.md

@@ -1,70 +1,156 @@
 # Plan Shapes
 
-Use this for strict-workflow, high-risk, durable, or delegated plans.
+Read this when choosing the structure, destination, identity, or revision shape of an ordered Plan. Use only the sections the Plan needs.
 
-## Durable Plan Identity
+## Destination And Durable Identity
 
-When saving a plan that future agents or teammates will rely on, start with a compact header:
+Follow repository convention when one exists.
+
+When [Track Work](../../track-work/SKILL.md) owns the task, store a task-local Plan in the `plans/` location it defines unless the Plan should become a canonical repository artifact.
+
+When no convention exists and future readers need durable identity, begin with a compact title and header:
 
 ```md
-> **Doc ID:** PLAN-001-billing-webhook-api
-> **Date:** 2026-05-26
-> **Owner:** Hassan Mohiddin
-> **Type:** Plan
-> **Status:** Ready
-> **Source:** docs/specs/billing-webhook-api.md
+# Billing Webhook Implementation Plan
+
+> **Doc ID:** PLAN-001-billing-webhook
+> **Type:** Implementation Plan
+> **Status:** Draft
+> **Owner:** <plan owner>
+> **Source:** <spec, issue, Working Record, diagnosis, or accepted context>
 ```
 
-Rules:
+Use one current status. Follow the repository or owner's vocabulary; useful states may include `Draft`, `Reviewed`, `Ready`, `Superseded`, and `Abandoned`. Writing or reviewing a Plan does not by itself make it `Ready`.
 
-- `Doc ID`: stable and readable. Prefer `PLAN-###-slug` when no repo convention exists.
-- `Owner`: use the spec/product owner when known. In normal workflow, use `User` only when the requester is the only known owner.
-- `Status`: use `Draft` when decisions/checks are still incomplete; use `Ready` when the plan is executable.
-- `Source`: cite the approved spec, clarified context, issue, ADR, or docs used as authority.
+Add dates, supersession links, or approvers only when useful and reliable.
 
-In strict-workflow for security, billing, privacy, public API, migration, data-loss, or architecture work, stop and ask if owner/status/source would be guessed.
+## Start With Source And Boundaries
 
-Do not add a changelog on first creation.
+Make the execution boundary and its dependencies clear:
+
+```text
+Goal:
+Source and linked artifacts:
+Scope:
+Non-goals:
+Accepted decisions:
+Assumptions:
+Dependencies:
+Required order:
+```
 
-## Lightweight Plans
+Link accepted behavior, architecture, and decisions instead of copying their rationale. Do not hide unsettled design or owner choices as assumptions. If an assumption could choose among materially different strategies, resolve it before treating the Plan as executable.
 
-Use for low-risk context-backed work:
+## Choose The Execution Shape
+
+### Lightweight Ordered Plan
+
+Use when the work is clear and short enough that phases add no value:
+
+```text
+Ordered actions or slices:
+Checks:
+Selected checkpoints, if any:
+Completion condition:
+```
+
+A tiny reversible action may not need a saved Plan.
+
+### Phased Implementation Plan
+
+Use when execution has meaningful dependencies, integration points, or several coherent outcomes:
+
+```text
+## Phase 1 — <outcome>
+Purpose:
+Dependencies:
+Selected checkpoints, if any:
+Completion condition:
+
+### Slice 1.1 — <result>
+Scope or boundary:
+Work:
+Checks:
+Completion condition:
+
+### Slice 1.2 — <result>
+...
+
+## Phase 2 — <outcome>
+...
+```
 
-- goal
-- source context
-- files likely touched
-- short slices
-- checks
+Describe the whole intended strategy with enough detail to inspect and execute it. If later phases cannot yet be planned honestly, use a Working Record instead.
 
-Mention that a spec is preferred when no approved spec exists, but do not add artifact pressure for tiny reversible work.
+## Define Phases And Slices
 
-## Normal Plans
+A phase groups slices that produce one meaningful integrated outcome. State its purpose, dependencies, and completion condition.
 
-Use for spec-backed feature work:
+For each slice, use only the fields needed to execute and check it:
+
+```text
+Intended result:
+Source requirement:
+Scope or write boundary:
+Work:
+Dependencies:
+Tests or observations:
+Verification claim and required boundary:
+Selected independent review, if any:
+Selected local commit, if any:
+Other user or continuity checkpoint, if any:
+Completion condition:
+```
+
+A slice is a coherent result, not a file list. Mention files, modules, or systems only when they clarify scope.
+
+Consider checkpoints at meaningful slice, phase, integration, risk, and continuity boundaries. Record only useful additions; normal verification and silent self-review need no repeated fields.
+
+A selected local commit names its coherent outcome and conditions, not merely “commit after this slice.” Plan approval authorizes listed local commits subject to live evidence and Commit Work inspection, but not push, integration, migration, deprecation, release, or launch. Record actual results and commit identities in the Working Record.
+
+## Adapt For The Work Type
+
+### Remediation
+
+After evidence or diagnosis establishes the cause, include the observed problem, source requirement, affected scope, ordered corrections, regression checks, recovery or cleanup, and completion condition. Do not plan from a requested patch or plausible cause alone.
+
+### Migration Or Operations
+
+For an accepted migration, release, rollout, or operational contract, include the source and target states, prerequisites, ordered execution or cohorts, checks before/during/after, stop or recovery conditions, observation, completion, and cleanup.
+
+The Plan implements accepted compatibility, safety, and recovery requirements; it does not invent them.
+
+## Finish With Integration And Invalidation
+
+End with the complete-result checks and conditions that would stop the Plan:
+
+```text
+Integration:
+Final tests or observations:
+Verification claims and required boundaries:
+Selected independent review, if any:
+Selected local commit, if any:
+Other user or continuity checkpoint, if any:
+Completion condition:
+
+Plan invalidation conditions:
+```
 
-- goal
-- source context
-- non-goals if the spec has them
-- files likely touched
-- vertical slices, each with tests/checks
-- stop conditions
-- final verification
+Useful invalidation conditions include:
 
-Each slice should produce a reviewable state, not just a list of files to edit.
+- a source requirement or accepted decision changes;
+- a material dependency behaves differently;
+- the design or architecture cannot satisfy the contract;
+- checks cannot establish the required claims;
+- implementation requires materially different scope or order;
+- accepted review items expose a Plan-level defect.
 
-## Strict Or Delegated Plans
+These conditions stop or revise the affected Plan. They are not alternate branches. Do not use a narrow final check to imply broader completion.
 
-Use for high-risk work or work another agent will execute:
+## Revise Or Supersede
 
-- durable plan identity
-- goal and source authority
-- explicit assumptions from source truth
-- likely files/modules, with "find existing pattern first" when unknown
-- vertical slices with expected red/green checks
-- review checkpoints before risky behavior lands
-- stop conditions for source-truth conflicts or owner-owned decisions
-- final verification and handoff criteria
+A local implementation detail, expected result, or completed slice does not revise the Plan.
 
-Call out sensitive boundaries directly: auth, public API shape, billing behavior, privacy/security, data loss, migrations, compatibility, and rollback.
+For a founded material change, update only the affected strategy and dependencies, record why it changed, preserve prior rationale, and update linked artifacts only when their content changed.
 
-Do not hide ambiguity as implementation detail. If endpoint shape, auth semantics, payload fields, billing behavior, or rollback expectations are missing, stop and ask before writing an executable plan.
+Use a superseding Plan when editing in place would obscure what was originally reviewed. Route a materially revised or superseding Plan through artifact review again.

package/skills/write-skill/SKILL.md

@@ -1,88 +1,119 @@
 ---
 name: write-skill
-description: Use when creating, rewriting, tightening, or reviewing an agent skill's instructions, trigger description, structure, examples, or bundled resources.
+description: Use when creating or revising an agent skill.
 ---
 
 # Write Skill
 
-Use Anthropic/Claude `skill-creator` guidance as the structure and progressive-disclosure authority when available. Do not copy it into this skill.
+Write the smallest agent-first skill that changes one named behavior.
 
-Use concise, behavior-shaping wording. Prefer sharp rules, concrete triggers, and stop conditions over explanation or filler.
+## Establish The First Read
 
-## Job
+Before writing, identify:
 
-Write the smallest skill that changes behavior.
+- the behavior and failure the skill must change;
+- the earliest natural prompt or situation where its guidance becomes useful;
+- the cues an agent can observe before reading the body;
+- the context guaranteed to be loaded before this skill;
+- a nearby case that should not be hijacked.
 
-Start with one `SKILL.md`. Add other files only when the skill would fail without them.
+A description cannot rely on terminology or classifications taught only inside the skill. The body must work for an agent reading it for the first time with only declared guaranteed context.
 
-Direct `/write-skill`, "production-ready", "complete", or "add examples/references/scripts if useful" does not override the smallest-skill default or the repo's skill-file rules.
+If public behavior, dependencies, safety, or compatibility remain unsettled, stop and resolve that boundary before encoding it.
 
-Do not add references, examples, README files, changelogs, or metadata when a compact `SKILL.md` can hold the behavior.
+## Preserve Before Substantial Revision
 
-Do not add helper scripts for commands the agent can run directly, such as `git log`, `git diff`, search, formatting, or line counts. Scripts are for repeated deterministic work that would be risky or wasteful to retype.
+Before rewriting or substantially editing an existing skill, snapshot the complete current package—`SKILL.md`, references, scripts, and other owned resources—and record an exact identity. Use a recoverable Git ref or task evidence outside the active package so the rewrite cannot replace its own baseline.
 
-Treat the repo's line budget as a best practice, not a hard cap. If none exists, aim to keep `SKILL.md` under 100 lines for normal skills. Let deep skills exceed it when the active rules, examples, or structure clearly earn their place.
+A small local wording correction does not need an extra snapshot when the exact prior state is already recoverable and the change does not alter behavior, dependencies, or package structure.
 
-## Description First
+## Write The Description
 
-The description controls activation. Make it specific enough to route the skill without making it broad enough to hijack unrelated work.
+Optimize for the first useful read, not repeated reads.
 
-Use:
+- State the broad core job in plain language.
+- Use cues observable in the user request or immediate task state.
+- Prefer broad recall when loading the skill is safe and the body can exit cleanly.
+- Do not require the agent to predict an internal classification taught only after activation.
+- Do not turn the description into an exhaustive trigger taxonomy or compressed summary of the body.
+- Treat “Use when…” as useful advice, not required grammar.
 
-- What the skill does.
-- When to use it.
-- Concrete trigger situations.
+A nearby case may pass by not loading the skill or by loading it and exiting without changing the task incorrectly. Do not narrow a description solely to prevent harmless reads, and do not broaden it until the skill routinely overrides the actual owning job.
 
-Avoid:
+Read [activation boundaries](references/activation-boundaries.md) when the boundary is unclear or evidence shows missed, late, early, or task-hijacking activation.
 
-- Generic helper language.
-- Marketing copy.
-- Long taxonomies.
-- Claims about quality.
+## Write For The Executing Agent
 
-## Wording Discipline
+1. Establish the skill’s job immediately.
+2. Define necessary terms before relying on them.
+3. Put rules where the agent first makes the affected choice.
+4. Keep the normal route understandable from `SKILL.md`; when it requires another resource, name that dependency and its read condition before relying on it.
+5. Say what to do, what not to do, and when to stop, exit, or route.
+6. Lead with required behavior. Use a negative instruction only to block a plausible or observed failure, and pair it with the positive action, exit, or route.
+7. Use direct instructions that change action or judgment.
+8. Include why only when it helps the agent generalize, choose correctly in an unseen case, or avoid a harmful literal reading.
+9. Repeat a shared rule only when a local reminder prevents a real failure; do not copy the owning workflow.
+10. Keep authoring status, evaluation summaries, evidence gaps, changelog notes, and readiness prose out of the executing skill.
 
-Every sentence should either route, constrain, stop, or guide behavior.
+Use discussion, research, and author reasoning to understand the target behavior. Do not copy conversation history, author debate, iteration notes, rejected drafts, or explanation written for collaborators into the skill. Translate that context into only the instructions, definitions, boundaries, and examples a first-time executing agent needs.
 
-Prefer sharp rules over explanations. Prefer one good example over a paragraph.
+A skill may rely on guaranteed base context. Do not assume an optional sibling skill, reference, or accidental earlier read. Link dependencies and state when to read them.
 
-Small wording changes can alter agent behavior. Change one pressure point at a time when possible.
+Read [agent-first instructions](references/agent-first-instructions.md) when wording, placement, undeclared context, or author explanation is obscuring execution.
 
-Use direct verbs:
+## Use Examples Deliberately
 
-- Inspect.
-- Stop.
-- Ask.
-- Do not edit.
-- Verify.
-- Report.
+Add a compact behavioral example when prose alone leaves a likely misclassification. Show the observable situation and the required action, stop, exit, or route.
 
-Avoid vague verbs:
+Keep examples general enough to transfer beyond one fixture. Do not turn the body into a transcript, test suite, or scenario catalog. Inline examples teach; behavioral evals test whether the skill changes behavior under pressure.
 
-- Consider.
-- Ensure.
-- Leverage.
-- Try to.
-- Be mindful.
+## Add Resources Only When Needed
 
-## Placement Discipline
+Read [progressive disclosure](references/progressive-disclosure.md) before adding or reorganizing references and scripts.
 
-Order rules by behavioral priority, not topic neatness.
+Start with one `SKILL.md`. Remove repeated prose and low-value checklists before expanding the file set.
 
-Put hard stop conditions before normal workflow details.
+- Add a required reference when normal execution genuinely needs separately owned depth; link it before the dependency is used.
+- Add a conditional reference when a distinct branch needs depth that would obscure the normal route; state the observable condition for reading it.
+- Add a script for repeated deterministic work or a feature the skill owns when automation is safer, clearer, or materially less wasteful than retyping it.
+- Link every agent-facing reference, asset, declared dependency, and executable entrypoint from `SKILL.md`; internal implementation modules need not be linked.
+- Keep owned resources inside the skill package unless a declared package dependency is required.
+- Treat unlinked-file inspection as factual inventory, not an automatic defect.
+- Do not add resources merely to make the package look complete.
 
-Put source-of-truth, user-owned decision, safety, and verification rules above convenience rules.
+There is no universal body template, section inventory, wording rule, file-count target, or requirement that a script follow an earlier failure.
 
-Do not hide the real constraint in a later caveat.
+## Evaluate The Behavioral Claim
 
-## Revision Rule
+Static validation proves structure, not activation or behavior. Name the exact claim being tested: description activation, first-read body behavior, nearby behavior, dependency composition, retained use, or artifact outcome.
 
-Do not add prose because the skill "could be clearer." Add or move wording because an eval, user failure, or concrete pressure case showed a behavior gap.
+Use [Evaluate Skill](../evaluate-skill/SKILL.md) to compare exact baseline and candidate environments under fixed declared inputs. Preserve adequate existing evidence, revise one measured pressure point at a time, and rerun the complete fixed group after a behavioral change.
 
-When improving a skill after a failure:
+Do not claim activation from body injection, retained use from one turn, or dependency behavior from ambient context. Keep behavior conclusions and missing evidence in the owning evaluation, Working Record, or delivery response rather than annotating the executing skill.
 
-1. Name the failed behavior.
-2. Find the sentence that should have prevented it.
-3. Tighten wording or placement.
-4. Keep unrelated sections still.
-5. Re-run the smallest relevant eval.
+## Check The Package
+
+Use the bundled [skill author](scripts/skill-author.mjs) for deterministic structure work:
+
+```text
+node <write-skill-directory>/scripts/skill-author.mjs init <directory> --name <name> --description <text>
+node <write-skill-directory>/scripts/skill-author.mjs validate <directory> [--package-root <directory>]
+node <write-skill-directory>/scripts/skill-author.mjs inspect <directory> [--package-root <directory>]
+```
+
+Choose the command by job:
+
+- `init`: use only for a new package. It creates the directory and minimal `SKILL.md` and refuses to overwrite an existing one.
+- `validate`: use after structural or resource changes and before claiming structural validity. It checks frontmatter, the top-level heading, recursive links, package dependencies, cycles, and containment.
+- `inspect`: use when body sizes, resource classes, scripts, unlinked files, and validation findings are needed. It reports facts rather than quality.
+
+Commands emit JSON. Invalid structure still emits its report and exits nonzero; command errors emit structured error JSON.
+
+- Package root defaults to the nearest `package.json` ancestor, falling back to the skill directory’s parent. Use `--package-root` to set it explicitly.
+- Frontmatter accepts flat plain strings or JSON-compatible double-quoted strings. Double-quote values when there is any ambiguity, especially punctuation, numbers, booleans, or null-like text.
+
+Never import or invoke deprecated tooling.
+
+## Stop
+
+Stop when the requested skill is minimal, executable on first read, honest about its dependencies, and free of author-facing status. Stop and ask when public behavior, activation boundaries, dependencies, safety, or compatibility cannot be settled from evidence. Do not add resources or procedure merely to make the package look complete.

package/skills/write-skill/references/activation-boundaries.md

@@ -0,0 +1,62 @@
+# Activation Boundaries
+
+Read this when an activation boundary is unclear or evidence shows missed, late, early, or task-hijacking activation.
+
+A description should make the skill available at the earliest useful moment without requiring language introduced by the skill itself.
+
+## Diagnose The First Read
+
+Identify:
+
+- the earliest natural prompt or state where the method can change behavior;
+- cues visible before the body is read;
+- context guaranteed before activation;
+- the consequence of missing that read;
+- the consequence if a nearby prompt also loads the skill.
+
+Do not optimize for repeated reads. Diagnose the first decision the skill should influence.
+
+## Check The Cues
+
+Useful cues include the skill’s job, natural user verbs, visible task situations, and distinctions from neighboring jobs.
+
+Reject cues that depend on:
+
+- vocabulary defined only in the body or an optional sibling;
+- future-duration guesses;
+- unexplained classifications or named phases;
+- generic “help with” or “improve” language;
+- marketing claims or exhaustive trigger catalogs.
+
+Guaranteed base context may define a term. Otherwise use plain observable language.
+
+## Test Nearby Behavior
+
+A nearby case can pass in two ways:
+
+- **Non-trigger:** the skill should not load.
+- **Safe read:** loading is acceptable, but the body exits or defers without applying the wrong method.
+
+Do not narrow a description solely to prevent harmless reads. Do not broaden it until the skill routinely overrides the actual owning job.
+
+## Examples
+
+Broad core trigger:
+
+> Use when committing work.
+
+Over-specified trigger that hides the job behind later workflow details:
+
+> Use after final verification when a planned checkpoint requires a locally reviewable commit.
+
+Broad safe-read trigger:
+
+> Use when working with software design—especially boundaries, interfaces, ownership, state, and failure behavior.
+
+The body can exit when the local interface remains sound; the description need not encode every structural-pressure case.
+
+## Evidence Boundary
+
+Natural activation proves the host read the exact skill snapshot from a natural prompt. Explicit body delivery tests first-read instructions, not activation. Composition tests declared dependencies. Multi-turn evidence tests later use. Artifact or transcript evidence shows whether the loaded skill helped or hijacked behavior.
+
+Preserve the earliest useful positive prompt and at least one close nearby case before making a broad activation claim.