{"id":"b82c7758-0577-4113-9c1a-2fea27677828","shortId":"qyaSSj","kind":"skill","title":"writing-plans","tagline":"Use when you have a spec or requirements for a multi-step task, before touching code","description":"# Execute\n\n→ Have approved spec/requirements? → **Write implementation plan. Assume engineer has zero context.**\n  1. Scope check: fact/assumption/unknown, baseline, Ripple Signal Triage, compatibility boundary, dual-track needs\n  2. File map: what files created/modified, clear boundaries, follow existing patterns\n  3. Bite-sized tasks (2-5 min each): exact file paths, complete code, exact commands, expected output\n  4. Self-review: spec coverage, placeholders, type consistency, compatibility, verification, dual-track\n  5. Save → offer execution choice (subagent-driven or inline)\n→ Plan must answer: problem, baseline, files, compat, verification, risks, retirement.\n\n# Writing Plans\n\n## Overview\n\nWrite comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.\n\nAssume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.\n\nThis skill is the canonical planning workflow for multi-step implementation work. Use it to convert approved specs or requirements into plans that are executable, testable, impact-aware, and bounded by compatibility and authority constraints.\n\n**Announce at start:** \"I'm using the writing-plans skill to create the implementation plan.\"\n\n**Context:** This should be run in a dedicated worktree (created by brainstorming skill).\n\n**Input:** approved requirements, a Spec Brief, or a Design Spec.\n\n**Save plans to:** `docs/aegis/plans/YYYY-MM-DD-<feature-name>.md`\nPlan always goes to `plans/` — never to `work/`.\n(User preferences for plan location override this default.)\n\nIf `docs/aegis/` does not exist and configured Aegis workspace support is\navailable, initialize the target project first:\n\n```bash\npython <aegis-workspace-helper> init --root <target-project-root>\n```\n\nIf installed Aegis workspace support is unavailable, initialize the workspace manually:\n  1. Create `docs/aegis/README.md` and `docs/aegis/INDEX.md`\n  2. Create `docs/aegis/BASELINE-GOVERNANCE.md` from template\n  3. If the project has code, create `docs/aegis/baseline/YYYY-MM-DD-initial-baseline.md`\nThen save the plan and append to `docs/aegis/INDEX.md`. Prefer:\n\n```bash\npython <aegis-workspace-helper> append-index --root <target-project-root> --path docs/aegis/plans/<filename>.md --kind plan --title \"<title>\"\npython <aegis-workspace-helper> check --root <target-project-root>\n```\n\n## Scope Check\n\nIf the input is a Spec Brief, keep the plan scoped to the pinned\nwhat/why/acceptance and do not expand into a formal design unless new\narchitecture, contract, migration, or cross-module uncertainty appears.\n\nCompact output contract before writing the plan: `Plan Basis`, `Files`,\n`Compatibility`, `Tasks`, `Risks`, and `Retirement`. Expand only where the\napproved scope, risk, or verification surface requires it.\n\nIf the spec covers multiple independent subsystems, suggest breaking into\nseparate plans. Before writing tasks, check: fact/assumption/unknown, baseline\ndocs, compatibility boundary, whether dual-track (repair + retirement) applies.\nIf approved requirements or the design carried an ADR signal, preserve the ADR\nsignal, source refs, real alternatives, compatibility boundary, and expected\nbaseline-sync questions for completion so ADR Auto Backfill can run without\nrediscovering the decision from scratch.\n\nIf task decomposition would encode a new owner, duplicate owner, fallback,\nadapter, compat-only carrier, delete-first question, unverified assumption, or\nlong-term stability claim that the spec did not already settle, use\n`first-principles-review` and its `Decision Hygiene Review` before task\ndecomposition.\n\n## Aegis Project Workspace\n\nWorkspace creation is triggered by the plan save step. See `using-aegis/SKILL.md` Rule 3 for the hard binary rule. If the project already has docs/adr/ or architecture docs, reference them — do not duplicate authority.\n\n## File Structure\n\nMap files before defining tasks. Design units with clear boundaries and single responsibilities. Files that change together should live together. Follow existing codebase patterns. Each task should produce self-contained, independently reviewable changes.\n\n## Required Planning Outputs\n\nBefore you leave this workflow, the written plan must make these items answerable:\n\n1. **What problem or approved scope this plan is implementing**\n2. **Which baseline docs, ADRs, or requirements shaped the plan**\n3. **What files own the change**\n4. **What compatibility boundary must hold**\n5. **What verification proves each major slice**\n6. **What risks, rollback surface, or unknowns remain**\n7. **What old owner / fallback / patch stays, shrinks, or retires when applicable**\n8. **Whether Ripple Signal Triage expands owner, downstream, contract, source-of-truth, or verification scope**\n9. **What ADR signals, source refs, alternatives, or baseline-sync questions must be preserved for completion when durable architecture decisions are in scope**\n\n## Bite-Sized Task Granularity\n\n**Each step is one action (2-5 minutes):**\n- \"Write the failing test\" - step\n- \"Run it to make sure it fails\" - step\n- \"Implement the minimal code to make the test pass\" - step\n- \"Run the tests and make sure they pass\" - step\n- \"Commit\" - step\n\n## Plan Document Header\n\nEvery plan MUST start with: Goal, Architecture, Tech Stack, Baseline/Authority Refs, Compatibility Boundary, Verification. See template in this directory.\n\n## Task Structure\n\nEach task: Files (create/modify/test paths), Why (user/business value), Impact/Compatibility, Verification (exact commands), then 5 checkbox steps: Write test → Verify RED → Minimal code → Verify GREEN → Commit. Every step must include complete code and exact commands.\n\nFor bug fixes, refactors, contract changes, or governance cleanup, add Repair Track (root cause, canonical owner, minimal change, compat boundary, verification) and Retirement Track (old owner/fallback, active status, keep reason or deletion trigger) inside the relevant task. If Ripple Signal Triage fired, include the affected downstream consumers and expanded verification path in the same task.\n\n## No Placeholders\n\nNever write: \"TBD\", \"TODO\", \"implement later\", \"fill in details\", \"Add appropriate error handling\", \"Write tests for the above\" without actual test code, \"Similar to Task N\" without repeating code. Every step must contain complete, copy-paste-ready content.\n\n## Self-Review\n\nCheck plan against spec: 1) Spec coverage — can you point to a task for each\nrequirement? 2) Placeholder scan — any TBD/TODO/vague instructions? 3) Type\nconsistency — do signatures match across tasks? 4) Compatibility — invariants,\nnon-goals, stable interfaces marked? 5) Verification — every major task has\nexact verification steps? 6) Dual-track — old logic addressed? 7) Decision\nhygiene — if `first-principles-review` was needed, did the plan preserve its\nowner / retirement / falsification findings? 8) ADR signal preservation — if\ndurable architecture decisions are in scope, did the plan preserve source refs,\nalternatives, compatibility boundary, and baseline-sync questions for\ncompletion?\n\nFix issues inline. Re-review is not needed — just fix and move on.\n\n## Execution Handoff\n\nAfter saving the plan, offer execution choice:\n\n**\"Plan complete and saved to `docs/aegis/plans/<filename>.md`. Two execution options:**\n\n**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration\n\n**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints\n\n**Which approach?\"**\n\n**If Subagent-Driven chosen:**\n- **REQUIRED SUB-SKILL:** Use aegis:subagent-driven-development\n- Fresh subagent per task + two-stage review\n\n**If Inline Execution chosen:**\n- **REQUIRED SUB-SKILL:** Use aegis:executing-plans\n- Batch execution with checkpoints for review\n\n## Planning Boundaries\n\n- A plan can define implementation slices, verification, rollback surface, and retirement expectations\n- A plan cannot grant authoritative completion\n- A plan should prepare runtime-ready execution, not pretend to be runtime authority","tags":["writing","plans","aegis","ganyuanran","add","agent-skills","ai-agents","ai-coding","baseline-first","claude-code","codex","coding-agents"],"capabilities":["skill","source-ganyuanran","skill-writing-plans","topic-add","topic-agent-skills","topic-ai-agents","topic-ai-coding","topic-baseline-first","topic-claude-code","topic-codex","topic-coding-agents","topic-evidence-driven","topic-first-principles","topic-opencode","topic-software-architecture"],"categories":["Aegis"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/GanyuanRan/Aegis/writing-plans","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add GanyuanRan/Aegis","source_repo":"https://github.com/GanyuanRan/Aegis","install_from":"skills.sh"}},"qualityScore":"0.581","qualityRationale":"deterministic score 0.58 from registry signals: · indexed on github topic:agent-skills · 262 github stars · SKILL.md body (8,367 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:54:50.801Z","embedding":null,"createdAt":"2026-05-04T19:05:09.525Z","updatedAt":"2026-05-18T18:54:50.801Z","lastSeenAt":"2026-05-18T18:54:50.801Z","tsv":"'-5':64,746 '/skill.md':561 '1':33,324,636,943,1073 '2':47,63,329,646,745,955,1090 '3':58,334,563,656,961 '4':76,662,969 '5':90,668,819,978 '6':675,987 '7':683,994 '8':695,1013 '9':711 'across':967 'action':744 'activ':866 'actual':916 'adapt':508 'add':849,906 'address':993 'adr':465,469,486,650,713,1014 'aegi':299,315,545,560,1118,1140 'affect':884 'almost':177 'alreadi':530,572 'altern':474,717,1030 'alway':277 'announc':232 'answer':102,635 'appear':401 'append':347,354 'append-index':353 'appli':456 'applic':694 'approach':1107 'appropri':907 'approv':23,212,262,421,458,640 'architectur':393,576,730,791,1019 'assum':28,117,169,185 'assumpt':518 'author':230,583,1183 'authorit':1168 'auto':487 'avail':303 'awar':224 'backfil':488 'baselin':37,104,446,480,648,720,1035 'baseline-sync':479,719,1034 'baseline/authority':794 'bash':309,351 'basi':410 'batch':1102,1144 'binari':567 'bite':60,161,736 'bite-s':59,160,735 'bound':226 'boundari':42,54,449,476,595,665,797,859,1032,1151 'brainstorm':259 'break':437 'brief':266,374 'bug':841 'cannot':1166 'canon':199,854 'carri':463 'carrier':512 'caus':853 'chang':601,619,661,845,857 'check':35,149,364,367,444,939 'checkbox':820 'checkpoint':1105,1147 'choic':94,1062 'chosen':1112,1134 'claim':524 'cleanup':848 'clear':53,594 'code':20,71,142,339,764,827,836,918,925 'codebas':125,608 'command':73,817,839 'commit':168,780,830 'compact':402 'compat':41,85,106,228,412,448,475,510,664,796,858,970,1031 'compat-on':509 'complet':70,484,727,835,930,1039,1064,1169 'comprehens':114 'configur':298 'consist':84,963 'constraint':231 'consum':886 'contain':616,929 'content':935 'context':32,122,248 'contract':394,404,703,844 'convert':211 'copi':932 'copy-paste-readi':931 'cover':432 'coverag':81,945 'creat':244,257,325,330,340 'create/modify/test':809 'created/modified':52 'creation':549 'cross':398 'cross-modul':397 'decis':494,539,731,995,1020 'decomposit':499,544 'dedic':255 'default':291 'defin':589,1155 'delet':514,871 'delete-first':513 'design':192,269,390,462,591 'detail':905 'develop':174,1122 'directori':803 'dispatch':1079 'doc':144,447,577,649 'docs/adr':574 'docs/aegis':293 'docs/aegis/baseline-governance.md':331 'docs/aegis/baseline/yyyy-mm-dd-initial-baseline.md':341 'docs/aegis/index.md':328,349 'docs/aegis/plans':358,1068 'docs/aegis/plans/yyyy-mm-dd-':274 'docs/aegis/readme.md':326 'document':129,783 'domain':184 'downstream':702,885 'dri':164 'driven':97,1076,1111,1121 'dual':44,88,452,989 'dual-track':43,87,451,988 'duplic':505,582 'durabl':729,1018 'encod':501 'engin':29,119 'error':908 'everi':785,831,926,980 'everyth':130 'exact':67,72,816,838,984 'execut':21,93,220,1054,1061,1071,1092,1093,1100,1103,1133,1142,1145,1177 'executing-plan':1099,1141 'exist':56,296,607 'expand':386,417,700,888 'expect':74,478,1163 'fact/assumption/unknown':36,445 'fail':750,759 'fallback':507,687 'falsif':1011 'fast':1088 'file':48,51,68,105,136,411,584,587,599,658,808 'fill':903 'find':1012 'fire':881 'first':308,515,534,999 'first-principles-review':533,998 'fix':842,1040,1050 'follow':55,606 'formal':389 'frequent':167 'fresh':1081,1123 'give':154 'goal':790,974 'goe':278 'good':190 'govern':847 'grant':1167 'granular':739 'green':829 'handl':909 'handoff':1055 'hard':566 'header':784 'hold':667 'hygien':540,996 'impact':223 'impact-awar':222 'impact/compatibility':814 'implement':26,115,206,246,645,761,901,1156 'includ':834,882 'independ':434,617 'index':355 'init':311 'initi':304,320 'inlin':99,1042,1091,1132 'input':261,370 'insid':873 'instal':314 'instruct':960 'interfac':976 'invari':971 'issu':1041 'item':634 'iter':1089 'keep':375,868 'kind':360 'know':134,176,189 'later':902 'leav':625 'live':604 'locat':288 'logic':992 'long':521 'long-term':520 'm':236 'major':673,981 'make':632,756,766,775 'manual':323 'map':49,586 'mark':977 'match':966 'md':275,359,1069 'might':146 'migrat':395 'min':65 'minim':763,826,856 'minut':747 'modul':399 'move':1052 'multi':15,204 'multi-step':14,203 'multipl':433 'must':101,631,666,723,787,833,928 'n':922 'need':46,132,147,1003,1048 'never':281,897 'new':392,503 'non':973 'non-goal':972 'noth':178 'offer':92,1060 'old':685,864,991 'one':743 'option':1072 'output':75,403,622 'overrid':289 'overview':112 'owner':504,506,686,701,855,1009 'owner/fallback':865 'pass':769,778 'past':933 'patch':688 'path':69,357,810,890 'pattern':57,609 'per':1083,1125 'pin':381 'placehold':82,896,956 'plan':3,27,100,111,116,158,200,217,241,247,272,276,280,287,345,361,377,408,409,440,554,621,630,643,655,782,786,940,1006,1026,1059,1063,1101,1143,1150,1153,1165,1171 'point':948 'prefer':285,350 'prepar':1173 'preserv':467,725,1007,1016,1027 'pretend':1179 'principl':535,1000 'problem':103,183,638 'produc':613 'project':307,337,546,571 'prove':671 'python':310,352,363 'question':127,482,516,722,1037 're':1044 're-review':1043 'readi':934,1176 'real':473 'reason':869 'recommend':1077 'red':825 'rediscov':492 'ref':472,716,795,1029 'refactor':843 'refer':578 'relev':875 'remain':682 'repair':454,850 'repeat':924 'requir':11,215,263,427,459,620,652,954,1113,1135 'respons':598 'retir':109,416,455,692,862,1010,1162 'review':79,536,541,618,938,1001,1045,1085,1130,1149 'rippl':38,697,878 'risk':108,414,423,677 'rollback':678,1159 'root':312,356,365,852 'rule':562,568 'run':252,490,753,771 'runtim':1175,1182 'runtime-readi':1174 'save':91,271,343,555,1057,1066 'scan':957 'scope':34,366,378,422,641,710,734,1023 'scratch':496 'see':557,799 'self':78,615,937 'self-contain':614 'self-review':77,936 'separ':439 'session':1097 'settl':531 'shape':653 'shrink':690 'signal':39,466,470,698,714,879,1015 'signatur':965 'similar':919 'singl':597 'size':61,162,737 'skill':173,196,242,260,1116,1138 'skill-writing-plans' 'slice':674,1157 'sourc':471,705,715,1028 'source-ganyuanran' 'source-of-truth':704 'spec':9,80,213,265,270,373,431,527,942,944 'spec/requirements':24 'stabil':523 'stabl':975 'stack':793 'stage':1129 'start':234,788 'status':867 'stay':689 'step':16,205,556,741,752,760,770,779,781,821,832,927,986 'structur':585,805 'sub':1115,1137 'sub-skil':1114,1136 'subag':96,1075,1082,1110,1120,1124 'subagent-driven':95,1074,1109 'subagent-driven-develop':1119 'subsystem':435 'suggest':436 'support':301,317 'sure':757,776 'surfac':426,679,1160 'sync':481,721,1036 'target':306 'task':17,62,141,163,413,443,498,543,590,611,738,804,807,876,894,921,951,968,982,1084,1087,1094,1126 'tast':128 'tbd':899 'tbd/todo/vague':959 'tdd':166 'tech':792 'templat':333,800 'term':522 'test':143,152,191,751,768,773,823,911,917 'testabl':221 'titl':362 'todo':900 'togeth':602,605 'toolset':181 'topic-add' 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-baseline-first' 'topic-claude-code' 'topic-codex' 'topic-coding-agents' 'topic-evidence-driven' 'topic-first-principles' 'topic-opencode' 'topic-software-architecture' 'touch':19,138 'track':45,89,453,851,863,990 'triag':40,699,880 'trigger':551,872 'truth':707 'two':1070,1128 'two-stag':1127 'type':83,962 'unavail':319 'uncertainti':400 'unit':592 'unknown':681 'unless':391 'unverifi':517 'use':4,208,237,532,559,1098,1117,1139 'user':284 'user/business':812 'using-aegi':558 'valu':813 'verif':86,107,425,670,709,798,815,860,889,979,985,1158 'verifi':824,828 'well':194 'what/why/acceptance':382 'whether':450,696 'whole':157 'without':491,915,923 'work':207,283 'workflow':201,627 'workspac':300,316,322,547,548 'worktre':256 'would':500 'write':2,25,110,113,240,406,442,748,822,898,910 'writing-plan':1,239 'written':629 'yagni':165 'zero':31,121","prices":[{"id":"077a58b3-26fd-48bc-81de-577906f320e3","listingId":"b82c7758-0577-4113-9c1a-2fea27677828","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"GanyuanRan","category":"Aegis","install_from":"skills.sh"},"createdAt":"2026-05-04T19:05:09.525Z"}],"sources":[{"listingId":"b82c7758-0577-4113-9c1a-2fea27677828","source":"github","sourceId":"GanyuanRan/Aegis/writing-plans","sourceUrl":"https://github.com/GanyuanRan/Aegis/tree/main/skills/writing-plans","isPrimary":false,"firstSeenAt":"2026-05-04T19:05:09.525Z","lastSeenAt":"2026-05-18T18:54:50.801Z"}],"details":{"listingId":"b82c7758-0577-4113-9c1a-2fea27677828","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"GanyuanRan","slug":"writing-plans","github":{"repo":"GanyuanRan/Aegis","stars":262,"topics":["add","agent-skills","ai-agents","ai-coding","architecture-driven-development","baseline-first","claude-code","codex","coding-agents","evidence-driven","first-principles","opencode","software-architecture","tdd","tlref"],"license":"mit","html_url":"https://github.com/GanyuanRan/Aegis","pushed_at":"2026-05-18T11:05:01Z","description":"Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks.","skill_md_sha":"4b4da3b92e4b79f96886e5b431fb835a5d143e24","skill_md_path":"skills/writing-plans/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/GanyuanRan/Aegis/tree/main/skills/writing-plans"},"layout":"multi","source":"github","category":"Aegis","frontmatter":{"name":"writing-plans","description":"Use when you have a spec or requirements for a multi-step task, before touching code"},"skills_sh_url":"https://skills.sh/GanyuanRan/Aegis/writing-plans"},"updatedAt":"2026-05-18T18:54:50.801Z"}}