@hassangameryt/freeflow 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/.agents/plugins/marketplace.json +20 -0
  2. package/.claude-plugin/marketplace.json +22 -0
  3. package/LICENSE +21 -0
  4. package/README.md +217 -0
  5. package/package.json +53 -0
  6. package/plugins/freeflow/.claude-plugin/plugin.json +20 -0
  7. package/plugins/freeflow/.codex-plugin/plugin.json +44 -0
  8. package/plugins/freeflow/assets/freeflow-plugin-icon-transparent.png +0 -0
  9. package/plugins/freeflow/command-surface.json +85 -0
  10. package/plugins/freeflow/docs/README.md +39 -0
  11. package/plugins/freeflow/docs/adr/0001-three-modes.md +27 -0
  12. package/plugins/freeflow/docs/adr/0002-evals-before-hooks.md +17 -0
  13. package/plugins/freeflow/docs/adr/0003-release-boundary.md +21 -0
  14. package/plugins/freeflow/docs/adr/README.md +7 -0
  15. package/plugins/freeflow/docs/architecture.md +86 -0
  16. package/plugins/freeflow/docs/release-evidence.md +49 -0
  17. package/plugins/freeflow/docs/skills.md +44 -0
  18. package/plugins/freeflow/docs/workflow.md +57 -0
  19. package/plugins/freeflow/hooks/freeflow-runtime-context.mjs +240 -0
  20. package/plugins/freeflow/hooks/hooks.json +18 -0
  21. package/plugins/freeflow/pi-extension/index.js +250 -0
  22. package/plugins/freeflow/skills/bypass/SKILL.md +68 -0
  23. package/plugins/freeflow/skills/capture-decisions/SKILL.md +95 -0
  24. package/plugins/freeflow/skills/capture-decisions/references/destination-guide.md +65 -0
  25. package/plugins/freeflow/skills/commit-work/SKILL.md +97 -0
  26. package/plugins/freeflow/skills/commit-work/references/staging-decisions.md +51 -0
  27. package/plugins/freeflow/skills/diagnose-failure/SKILL.md +95 -0
  28. package/plugins/freeflow/skills/diagnose-failure/references/feedback-loop-catalog.md +25 -0
  29. package/plugins/freeflow/skills/diagnose-failure/references/flaky-and-performance.md +31 -0
  30. package/plugins/freeflow/skills/evaluate-skill/SKILL.md +96 -0
  31. package/plugins/freeflow/skills/evaluate-skill/references/eval-patterns.md +41 -0
  32. package/plugins/freeflow/skills/evaluate-skill/references/grading-priority.md +33 -0
  33. package/plugins/freeflow/skills/execute-plan/SKILL.md +67 -0
  34. package/plugins/freeflow/skills/grill-context/SKILL.md +79 -0
  35. package/plugins/freeflow/skills/grill-context/references/approach-framing.md +52 -0
  36. package/plugins/freeflow/skills/handoff/SKILL.md +66 -0
  37. package/plugins/freeflow/skills/handoff/references/templates.md +64 -0
  38. package/plugins/freeflow/skills/interview-gate/SKILL.md +90 -0
  39. package/plugins/freeflow/skills/mode-contract/SKILL.md +79 -0
  40. package/plugins/freeflow/skills/research-brief/SKILL.md +69 -0
  41. package/plugins/freeflow/skills/review-artifact/SKILL.md +82 -0
  42. package/plugins/freeflow/skills/review-artifact/references/reviewer-prompt.md +45 -0
  43. package/plugins/freeflow/skills/review-work/SKILL.md +73 -0
  44. package/plugins/freeflow/skills/review-work/references/reviewer-prompt.md +89 -0
  45. package/plugins/freeflow/skills/setup-freeflow/SKILL.md +84 -0
  46. package/plugins/freeflow/skills/setup-freeflow/references/activation-contract.md +94 -0
  47. package/plugins/freeflow/skills/setup-freeflow/references/host-setup.md +33 -0
  48. package/plugins/freeflow/skills/verify-work/SKILL.md +62 -0
  49. package/plugins/freeflow/skills/workflow/SKILL.md +87 -0
  50. package/plugins/freeflow/skills/workflow/references/workflow-map.md +103 -0
  51. package/plugins/freeflow/skills/write-plan/SKILL.md +88 -0
  52. package/plugins/freeflow/skills/write-plan/references/plan-shapes.md +70 -0
  53. package/plugins/freeflow/skills/write-skill/SKILL.md +88 -0
  54. package/plugins/freeflow/skills/write-spec/SKILL.md +90 -0
  55. package/plugins/freeflow/skills/write-spec/references/artifact-standards.md +67 -0
  56. package/plugins/freeflow/skills/write-spec/references/spec-shapes.md +69 -0
@@ -0,0 +1,94 @@
1
+ # Activation Contract
2
+
3
+ This is the canonical Freeflow setup contract. Setup renders this contract into host instruction files; docs, fixtures, and eval assertions should reference it or be checked against it.
4
+
5
+ ## Interface
6
+
7
+ Use this Markdown reference as the v0.1 contract module:
8
+
9
+ ```text
10
+ getActivationContract(defaultMode) -> ActivationContract
11
+ planActivation(contract, repoState, request) -> ActivationPlan | ActivationStop
12
+ renderActivation(contract, target) -> rendered text or checks
13
+ ```
14
+
15
+ Do not add a code module until setup behavior needs logic that cannot be kept clear in the skill and this reference.
16
+
17
+ ## Invariants
18
+
19
+ - Activation text contains always-on invariants only, not the full workflow spine.
20
+ - Config has exactly one field: `defaultMode`.
21
+ - Valid defaults are exactly `conversation`, `workflow`, and `strict-workflow`.
22
+ - Default mode is `workflow` unless the user explicitly persists another valid mode.
23
+ - Codex activation writes `AGENTS.md`, not `.codex/rules`.
24
+ - Claude activation writes a `CLAUDE.md` import plus one `.claude/rules/freeflow-core.md`.
25
+ - Multi-agent setup updates both host surfaces only on explicit request and reports drift risk.
26
+ - Existing repo instructions remain source truth.
27
+ - Setup hard-stops before unresolved host ambiguity or repo-rule conflict.
28
+ - Setup does not create repo-local hooks, docs inventories, state files, handoffs, empty `CONTEXT.md`, skill inventories, version metadata, activation path, current task, or current phase.
29
+ - Plugin-bundled context hooks may load workflow and interview-gate context at session start, but they are package runtime, not setup output.
30
+ - After successful setup verification, setup reads the workflow skill, workflow map, and interview-gate skill before its final response so the current session is immediately usable.
31
+
32
+ ## Host Adapters
33
+
34
+ Codex adapter:
35
+
36
+ - Update an existing `## Freeflow` block in `AGENTS.md`, or add one near existing agent/workflow instructions.
37
+ - Keep exactly one `## Freeflow` block.
38
+ - Never use `.codex/rules` for Freeflow behavior.
39
+
40
+ Claude adapter:
41
+
42
+ - Update `CLAUDE.md` with only the import block below.
43
+ - Write the Codex core block text to `.claude/rules/freeflow-core.md`.
44
+ - Keep exactly one imported core file unless the user explicitly confirms a split after the one-file recommendation.
45
+
46
+ Config adapter:
47
+
48
+ - Create or update `.freeflow/config.json`.
49
+ - Write exactly `{ "defaultMode": "<mode>" }`.
50
+ - Use `workflow` unless the user explicitly asks to persist `conversation` or `strict-workflow`.
51
+
52
+ ## Codex Core Block
53
+
54
+ <!-- freeflow-activation-contract:codex-core:start -->
55
+ ```md
56
+ ## Freeflow
57
+
58
+ Use Freeflow for consequential work. Default mode: `.freeflow/config.json`.
59
+
60
+ Move forward when context is sufficient. Re-enter clarification when new ambiguity would change the next action.
61
+
62
+ Treat questions as questions and suggestions as hypotheses. Answer directly; do not infer correction, permission, or agreement.
63
+
64
+ Ask before user-owned decisions: product behavior, scope, public APIs, security, privacy, billing, data loss, compatibility, permissions, or irreversible architecture.
65
+
66
+ Treat live repo evidence and existing docs/tests as source truth. If the user request conflicts with them, stop and ask before changing behavior.
67
+
68
+ Verify before completion claims. Capture only stable decisions, glossary terms, ADR-worthy tradeoffs, or useful handoff memory.
69
+ ```
70
+ <!-- freeflow-activation-contract:codex-core:end -->
71
+
72
+ ## Claude Import Block
73
+
74
+ <!-- freeflow-activation-contract:claude-import:start -->
75
+ ```md
76
+ ## Freeflow
77
+
78
+ @.claude/rules/freeflow-core.md
79
+ ```
80
+ <!-- freeflow-activation-contract:claude-import:end -->
81
+
82
+ ## Drift Checks
83
+
84
+ Run `plugins/freeflow/evals/scripts/check-activation-contract.sh` when changing setup behavior, post-setup fixtures, setup eval assertions, or docs that quote setup behavior.
85
+ Run `plugins/freeflow/evals/scripts/check-runtime-context-hook.sh` when changing plugin-bundled runtime context hooks.
86
+
87
+ The check keeps these surfaces aligned:
88
+
89
+ - this canonical reference
90
+ - `setup-freeflow/SKILL.md`
91
+ - `setup-freeflow/references/host-setup.md`
92
+ - `docs/freeflow-runtime-and-lifecycle.md`
93
+ - post-setup `AGENTS.md` fixtures
94
+ - setup eval assertions that depend on canonical activation text
@@ -0,0 +1,33 @@
1
+ # Host Setup
2
+
3
+ Use this only when setup asks for a host, profile, default mode, team install, hooks, CLI, or multi-agent shape. Use `activation-contract.md` for canonical activation text, config invariants, and host adapter rules.
4
+
5
+ ## Hosts
6
+
7
+ Codex setup writes `AGENTS.md` and `.freeflow/config.json`.
8
+
9
+ Claude setup writes `CLAUDE.md`, `.claude/rules/freeflow-core.md`, and `.freeflow/config.json`.
10
+
11
+ Multi-agent setup updates both host surfaces only when the user asks for both or multi-agent setup. Mention that duplicated always-on text can drift, render both hosts from `activation-contract.md`, and keep Claude's full block in one imported file.
12
+
13
+ Current runtime is not enough to choose a host when both `AGENTS.md` and `CLAUDE.md` exist.
14
+
15
+ ## Profiles
16
+
17
+ Solo setup is the default: one host target, compact activation, `defaultMode: "workflow"`, no extra docs.
18
+
19
+ Team setup still uses compact activation. Add both hosts only if requested. Do not add team standards, onboarding docs, owners, approvers, repo-local hooks, or CLI checks as part of setup unless the user separately asks and the repo has a validated path for them.
20
+
21
+ Strict setup changes `.freeflow/config.json` to `strict-workflow` only when the user explicitly asks to make that the repo default. Otherwise recommend strict-workflow for high-risk work without persisting it.
22
+
23
+ Valid persisted defaults are exactly `conversation`, `workflow`, and `strict-workflow`.
24
+
25
+ ## Not Setup
26
+
27
+ Do not install repo-local hooks, CLI commands, lint rules, global standards, docs inventories, or state files during setup.
28
+
29
+ Freeflow's plugin-bundled context hooks are package runtime. They load workflow and interview-gate context at session start, but setup should not copy hook files into the target repo.
30
+
31
+ After successful setup verification, setup should read the workflow skill, workflow map, and interview-gate skill before the final response. If session-start runtime context does not load in later sessions, tell the user to review/trust the installed Freeflow plugin hooks or start a fresh/compacted session. Do not create repo-local hook files as a workaround.
32
+
33
+ If the user asks for enforcement, say Freeflow setup is instruction-only for now and ask whether to handle enforcement as a separate task.
@@ -0,0 +1,62 @@
1
+ ---
2
+ name: verify-work
3
+ description: Use before claiming work is done, fixed, passing, implemented, reviewed, or ready; when verification fails; or when the user asks to skip checks but still wants a completion claim.
4
+ ---
5
+
6
+ # Verify Work
7
+
8
+ Do not claim completion without fresh evidence.
9
+
10
+ ## Evidence Rule
11
+
12
+ Before saying work is done, fixed, passing, implemented, reviewed, or ready, verify the claim.
13
+
14
+ Good evidence can be:
15
+
16
+ - Passing tests.
17
+ - Typecheck, lint, build, or formatter output.
18
+ - Reproducing a bug before and after a fix.
19
+ - Inspecting the changed file when no executable check exists.
20
+ - A targeted manual check.
21
+
22
+ Use the smallest verification that proves the claim.
23
+
24
+ ## Claim Rule
25
+
26
+ Match the claim to the evidence.
27
+
28
+ - If tests passed, say which tests passed.
29
+ - If only a file was inspected, say that.
30
+ - If no runnable check exists, say the work is unverified by automation.
31
+ - If the user asks to skip checks, skip the checks but do not claim verified or passing.
32
+
33
+ Never convert "I changed the code" into "it works" without evidence.
34
+
35
+ ## Failure Rule
36
+
37
+ If verification fails, stop and report the evidence.
38
+
39
+ Do not patch randomly. Decide whether the failure means:
40
+
41
+ - Implementation bug.
42
+ - Bad or stale test.
43
+ - Source-of-truth conflict.
44
+ - Missing environment/dependency.
45
+ - User-owned product/domain decision.
46
+
47
+ If the failure challenges the spec, plan, docs, policy, or tests, re-enter the interview gate before changing direction.
48
+
49
+ ## Final Response
50
+
51
+ Use this shape:
52
+
53
+ ```text
54
+ Changed: ...
55
+ Verified: ...
56
+ Not verified: ...
57
+ Next: ...
58
+ ```
59
+
60
+ For completed consequential work, `Next:` is mandatory. Omit it only for direct question answers, mid-task status, or clarification-only turns.
61
+
62
+ Keep it short.
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: workflow
3
+ description: Use when doing consequential work such as implementation, bug fixing, planning, research-for-action, review, verification, or handoff.
4
+ ---
5
+
6
+ # Workflow
7
+
8
+ Follow a lightweight forward workflow. Scale process to task risk.
9
+
10
+ Question means answer. Do not turn a question into a file edit, report, plan, or implementation.
11
+
12
+ ```text
13
+ Clarify / Research
14
+ -> Decision / Spec
15
+ -> Plan
16
+ -> Execute
17
+ -> Review
18
+ -> Verify
19
+ -> Handoff
20
+ ```
21
+
22
+ This is a guide, not ceremony. Small reversible work can skip spec/plan artifacts.
23
+
24
+ Read `references/workflow-map.md` when the user asks for the full pipeline, public docs need a diagram, or the next workflow entry point is unclear.
25
+
26
+ ## Route Closeout
27
+
28
+ When a consequential workflow phase completes, name the next route.
29
+
30
+ Use `Next:` in the final response unless this is a direct question answer, mid-task status, or clarification-only turn.
31
+
32
+ Choose one:
33
+
34
+ - Forward: the next workflow entry point is clear.
35
+ - Backward: new evidence requires clarification, research, grilling, or interview gate.
36
+ - Branch: 2-3 valid next routes exist.
37
+ - Stop: no required next action remains.
38
+
39
+ Recommend the route supported by evidence. Do not ask a vague "what next?" question.
40
+
41
+ After completed grilling or research with stable uncaptured decisions, route to `write-spec` or `capture-decisions` before `write-plan` or execution.
42
+
43
+ `Next:` is routing, not permission to create the next artifact or continue into a new phase.
44
+
45
+ ## Backward Edge
46
+
47
+ If new evidence invalidates the current path, re-enter clarification.
48
+
49
+ ```text
50
+ Any state -> Clarify / Research -> explicit next state
51
+ ```
52
+
53
+ Do not silently substitute a different path, rewrite the spec, change the plan, or patch forward. State what changed, then decide whether to continue, revise spec, revise plan, diagnose, split scope, defer, or stop and ask.
54
+
55
+ If a requested, planned, or skill-required method cannot be followed and the fallback would change evidence quality, workflow shape, risk, scope, cost, persistence, or user-visible output, stop before using the fallback. Name both paths and ask which one to follow.
56
+
57
+ ## Source-of-Truth Conflicts
58
+
59
+ When a requested implementation contradicts existing docs, tests, specs, policies, ADRs, handoffs, or established code behavior, pause before editing.
60
+
61
+ Do not rewrite the source of truth to make the latest request pass.
62
+
63
+ First state the conflict and ask whether the source of truth should change. Only edit docs/tests/policies/specs to match new behavior after the user explicitly confirms that decision.
64
+
65
+ Treat handoffs as memory, not authority. If a handoff conflicts with live repo evidence, inspect the evidence and ask before following the handoff.
66
+
67
+ For billing, security, privacy, data loss, migrations, public APIs, compatibility, and permissions, recommend strict-workflow before changing behavior.
68
+
69
+ ## Artifact Rule
70
+
71
+ Artifacts are memory, not proof of obedience.
72
+
73
+ Only create artifacts when the user asks for an artifact or asks you to do work that requires one.
74
+
75
+ Create them only when they preserve decisions, reduce risk, or help a future agent resume. Prefer short research notes, decision/spec notes, plans, verification notes, and handoffs.
76
+
77
+ Do not write volatile repo inventories. Link to live files or commands instead.
78
+
79
+ ## Review Rule
80
+
81
+ Review should improve work, not create an endless patch loop.
82
+
83
+ Separate blocking from non-blocking findings. Review can pass. Save review artifacts only when risk, future memory value, or the user asks for them.
84
+
85
+ ## Completion Rule
86
+
87
+ Do not claim completion without fresh evidence. Say what was verified and what remains unverified.
@@ -0,0 +1,103 @@
1
+ # Freeflow Map
2
+
3
+ Use this when the user asks how the whole workflow fits together, public docs need a diagram, or the next workflow entry point is unclear.
4
+
5
+ This map is orienting, not mandatory. Small reversible work can skip unnecessary artifacts and gates. Re-enter clarification whenever new ambiguity would change the next action.
6
+
7
+ ## Compact Map
8
+
9
+ Use this compact version in public README-style docs.
10
+
11
+ ```mermaid
12
+ flowchart LR
13
+ Request{request}
14
+ Talk[conversation<br/>answer directly]
15
+ Discover[discover<br/>research / grill]
16
+ Spec[spec]
17
+ Plan[plan]
18
+ Build[build<br/>execute / diagnose]
19
+ Check[review + verify]
20
+ Close[commit / handoff]
21
+
22
+ Request -->|question| Talk
23
+ Request -->|work| Discover
24
+ Discover --> Spec --> Plan --> Build --> Check --> Close
25
+ Check -. new evidence or failed check .-> Discover
26
+ ```
27
+
28
+ ```text
29
+ Use conversation mode for questions. Use workflow mode for consequential work.
30
+ Use strict-workflow for risky work; same spine, stronger gates.
31
+ Loop back when new evidence, source conflicts, user-owned decisions, or failed checks change the path.
32
+ After each completed consequential phase, name the next route: forward, backward, branch, or stop.
33
+ ```
34
+
35
+ ## Reference Map
36
+
37
+ Use this fuller version when choosing an entry point or explaining the workflow lifecycle.
38
+
39
+ ```mermaid
40
+ flowchart TD
41
+ Request([User request]) --> Mode{Mode}
42
+
43
+ Mode -->|question, critique, explanation| Conversation[conversation mode<br/>answer directly]
44
+ Conversation --> Done([done])
45
+
46
+ Mode -->|consequential work| Workflow[workflow mode<br/>scale to risk]
47
+ Mode -->|high-risk or hard to reverse| Strict[strict-workflow mode<br/>stronger gates]
48
+
49
+ Workflow --> Entry{Choose entry point}
50
+ Strict --> Entry
51
+
52
+ Entry --> Discovery[Discovery<br/>research-brief<br/>grill-context<br/>interview-gate]
53
+ Entry --> Spec[Spec<br/>write-spec<br/>review-artifact]
54
+ Entry --> Plan[Plan<br/>write-plan<br/>review-artifact]
55
+ Entry --> Build[Build or diagnose<br/>execute-plan<br/>diagnose-failure]
56
+ Entry --> Closeout[Closeout<br/>review-work<br/>verify-work<br/>commit-work]
57
+
58
+ Discovery --> Spec
59
+ Spec --> Plan
60
+ Plan --> Build
61
+ Build --> Closeout
62
+ Closeout --> Handoff[handoff<br/>capture-decisions when durable]
63
+ Handoff --> Done
64
+
65
+ Reenter[Re-enter discovery<br/>new evidence, owner decision,<br/>source conflict, or failed check]
66
+ Spec -.-> Reenter
67
+ Plan -.-> Reenter
68
+ Build -.-> Reenter
69
+ Closeout -.-> Reenter
70
+ Handoff -.-> Reenter
71
+ Reenter --> Discovery
72
+
73
+ Bypass[bypass<br/>skip ceremony, not judgment] -.-> Entry
74
+ ```
75
+
76
+ ## Common Entry Points
77
+
78
+ - Use `conversation mode` when the user asks a question, wants critique, or is exploring.
79
+ - Use `research-brief` when repo, domain, evidence, or current facts are unknown.
80
+ - Use `grill-context` or `interview-gate` when direction is vague, source truth conflicts, or user-owned decisions are still open.
81
+ - Use `write-spec` when requirements are agreed but not durable.
82
+ - Use `review-artifact` when a spec, plan, handoff, or decision note must guide future work.
83
+ - Use `write-plan` when an approved spec or explicit task context exists.
84
+ - Use `execute-plan` when an approved plan exists.
85
+ - Use `diagnose-failure` when behavior is broken, failing, flaky, slow, or unclear.
86
+ - Use `review-work` and `verify-work` before claiming consequential work is ready.
87
+ - Use `commit-work` only after the intended diff is reviewed and verification evidence exists.
88
+ - Use `handoff` when pausing, compacting, or transferring context.
89
+ - Use `capture-decisions` only for stable decisions, glossary terms, rejected approaches, or ADR-worthy tradeoffs.
90
+ - Use `bypass` only to skip unnecessary ceremony. It cannot skip user-owned decisions, source-truth conflicts, risky checks, or verification claims.
91
+
92
+ ## Phase Exits
93
+
94
+ End completed consequential phases with `Next:` unless this is a direct answer, mid-task status, or clarification-only turn.
95
+
96
+ - Forward: name the next entry point, such as `write-spec`, `write-plan`, `execute-plan`, `review-work`, `verify-work`, `commit-work`, or `handoff`.
97
+ - Backward: return to `interview-gate`, `research-brief`, or `grill-context` when evidence changes the path.
98
+ - Branch: show 2-3 valid next routes when more than one is reasonable.
99
+ - Stop: say no required next action remains.
100
+
101
+ After completed grilling or research with stable uncaptured decisions, prefer `write-spec` or `capture-decisions` before planning or execution.
102
+
103
+ Do not create the next artifact just because it is the next route.
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: write-plan
3
+ 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.
4
+ ---
5
+
6
+ # Write Plan
7
+
8
+ Classify the plan request first:
9
+
10
+ - Spec-backed: write the plan from the approved spec.
11
+ - Bug without feedback loop: ask for or propose the feedback loop. Do not write or save a fix plan.
12
+ - Hidden owner decision or source conflict: name it and do not write the plan.
13
+ - Context-backed: say a spec is preferred, then write a lightweight plan.
14
+ - Missing source context: ask for context or start grilling.
15
+
16
+ A plan executes source truth. It does not create it.
17
+
18
+ Do not write a plan that decides product behavior, scope, domain meaning, compatibility, public API behavior, security, privacy, billing, data-loss, or architecture.
19
+
20
+ 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.
21
+
22
+ Never skip docs, tests, specs, policies, ADRs, or live behavior because the prompt calls them stale. Inspect them, then classify the conflict.
23
+
24
+ If the user asks a question about a plan, answer the question. Do not create or edit the plan unless asked.
25
+
26
+ 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.
27
+
28
+ ## Source First
29
+
30
+ Before writing, inspect the current source context:
31
+
32
+ - Approved spec or explicit requirements.
33
+ - Relevant docs, ADRs, tests, policies, and existing code.
34
+ - Handoffs only as memory, not authority.
35
+
36
+ Live repo evidence overrides stale notes.
37
+
38
+ ## Normal Path
39
+
40
+ Prefer an approved spec.
41
+
42
+ 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.
43
+
44
+ For bug fixes, require a repro, failing test, or feedback loop before writing a fix plan.
45
+
46
+ 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.
47
+
48
+ Use vertical slices. Each slice should produce something testable.
49
+
50
+ ## Stop Conditions
51
+
52
+ Stop before writing when the plan would:
53
+
54
+ - Invent requirements from thin or adjacent context.
55
+ - Resolve a user-owned decision.
56
+ - Override docs, tests, specs, policies, ADRs, or live behavior.
57
+ - Treat a handoff, review comment, or plan as authority over source-of-truth files.
58
+ - Plan a bug fix without a repro, failing test, feedback loop, or accepted diagnostic risk.
59
+ - Turn a missing bug repro into guessed fix steps, TTLs, invalidation rules, concurrency rules, or instrumentation requirements.
60
+ - Hide uncertainty inside implementation steps.
61
+
62
+ Name the missing decision or conflict. Ask which path to follow. Recommend the path supported by evidence.
63
+
64
+ For source-truth conflicts, the final line must be a direct choice question.
65
+
66
+ ## Shape
67
+
68
+ Adapt the plan to risk. Prefer:
69
+
70
+ - Durable plan identity when the plan is saved for future agents or teammates.
71
+ - Goal.
72
+ - Source spec or context.
73
+ - Files likely touched.
74
+ - Vertical slices.
75
+ - Tests or checks per slice.
76
+ - Commands where known.
77
+ - Stop conditions.
78
+ - Review or verification checkpoints.
79
+
80
+ Keep it concise. Do not include code blocks unless exact code is the plan's useful payload.
81
+
82
+ ## Completion
83
+
84
+ After writing, report:
85
+
86
+ - The artifact path, if saved.
87
+ - The source context used.
88
+ - Any decisions still blocked.
@@ -0,0 +1,70 @@
1
+ # Plan Shapes
2
+
3
+ Use this for strict-workflow, high-risk, durable, or delegated plans.
4
+
5
+ ## Durable Plan Identity
6
+
7
+ When saving a plan that future agents or teammates will rely on, start with a compact header:
8
+
9
+ ```md
10
+ > **Doc ID:** PLAN-001-billing-webhook-api
11
+ > **Date:** 2026-05-26
12
+ > **Owner:** Hassan Mohiddin
13
+ > **Type:** Plan
14
+ > **Status:** Ready
15
+ > **Source:** docs/specs/billing-webhook-api.md
16
+ ```
17
+
18
+ Rules:
19
+
20
+ - `Doc ID`: stable and readable. Prefer `PLAN-###-slug` when no repo convention exists.
21
+ - `Owner`: use the spec/product owner when known. In normal workflow, use `User` only when the requester is the only known owner.
22
+ - `Status`: use `Draft` when decisions/checks are still incomplete; use `Ready` when the plan is executable.
23
+ - `Source`: cite the approved spec, clarified context, issue, ADR, or docs used as authority.
24
+
25
+ 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.
26
+
27
+ Do not add a changelog on first creation.
28
+
29
+ ## Lightweight Plans
30
+
31
+ Use for low-risk context-backed work:
32
+
33
+ - goal
34
+ - source context
35
+ - files likely touched
36
+ - short slices
37
+ - checks
38
+
39
+ Mention that a spec is preferred when no approved spec exists, but do not add artifact pressure for tiny reversible work.
40
+
41
+ ## Normal Plans
42
+
43
+ Use for spec-backed feature work:
44
+
45
+ - goal
46
+ - source context
47
+ - non-goals if the spec has them
48
+ - files likely touched
49
+ - vertical slices, each with tests/checks
50
+ - stop conditions
51
+ - final verification
52
+
53
+ Each slice should produce a reviewable state, not just a list of files to edit.
54
+
55
+ ## Strict Or Delegated Plans
56
+
57
+ Use for high-risk work or work another agent will execute:
58
+
59
+ - durable plan identity
60
+ - goal and source authority
61
+ - explicit assumptions from source truth
62
+ - likely files/modules, with "find existing pattern first" when unknown
63
+ - vertical slices with expected red/green checks
64
+ - review checkpoints before risky behavior lands
65
+ - stop conditions for source-truth conflicts or owner-owned decisions
66
+ - final verification and handoff criteria
67
+
68
+ Call out sensitive boundaries directly: auth, public API shape, billing behavior, privacy/security, data loss, migrations, compatibility, and rollback.
69
+
70
+ 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.
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: write-skill
3
+ description: Use when creating, rewriting, tightening, or reviewing an agent skill's instructions, trigger description, structure, examples, or bundled resources.
4
+ ---
5
+
6
+ # Write Skill
7
+
8
+ Use Anthropic/Claude `skill-creator` guidance as the structure and progressive-disclosure authority when available. Do not copy it into this skill.
9
+
10
+ Use concise, behavior-shaping wording. Prefer sharp rules, concrete triggers, and stop conditions over explanation or filler.
11
+
12
+ ## Job
13
+
14
+ Write the smallest skill that changes behavior.
15
+
16
+ Start with one `SKILL.md`. Add other files only when the skill would fail without them.
17
+
18
+ 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.
19
+
20
+ Do not add references, examples, README files, changelogs, or metadata when a compact `SKILL.md` can hold the behavior.
21
+
22
+ 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.
23
+
24
+ Follow the repo's line budget. If none exists, keep `SKILL.md` under 100 lines unless the extra lines clearly earn their place.
25
+
26
+ ## Description First
27
+
28
+ The description controls activation. Make it specific enough to route the skill without making it broad enough to hijack unrelated work.
29
+
30
+ Use:
31
+
32
+ - What the skill does.
33
+ - When to use it.
34
+ - Concrete trigger situations.
35
+
36
+ Avoid:
37
+
38
+ - Generic helper language.
39
+ - Marketing copy.
40
+ - Long taxonomies.
41
+ - Claims about quality.
42
+
43
+ ## Wording Discipline
44
+
45
+ Every sentence should either route, constrain, stop, or guide behavior.
46
+
47
+ Prefer sharp rules over explanations. Prefer one good example over a paragraph.
48
+
49
+ Small wording changes can alter agent behavior. Change one pressure point at a time when possible.
50
+
51
+ Use direct verbs:
52
+
53
+ - Inspect.
54
+ - Stop.
55
+ - Ask.
56
+ - Do not edit.
57
+ - Verify.
58
+ - Report.
59
+
60
+ Avoid vague verbs:
61
+
62
+ - Consider.
63
+ - Ensure.
64
+ - Leverage.
65
+ - Try to.
66
+ - Be mindful.
67
+
68
+ ## Placement Discipline
69
+
70
+ Order rules by behavioral priority, not topic neatness.
71
+
72
+ Put hard stop conditions before normal workflow details.
73
+
74
+ Put source-of-truth, user-owned decision, safety, and verification rules above convenience rules.
75
+
76
+ Do not hide the real constraint in a later caveat.
77
+
78
+ ## Revision Rule
79
+
80
+ 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.
81
+
82
+ When improving a skill after a failure:
83
+
84
+ 1. Name the failed behavior.
85
+ 2. Find the sentence that should have prevented it.
86
+ 3. Tighten wording or placement.
87
+ 4. Keep unrelated sections still.
88
+ 5. Re-run the smallest relevant eval.