{"id":"dae36c73-6e75-4aeb-ba49-56cb20e3d0c6","shortId":"7yVGrG","kind":"skill","title":"alignfirst-coaching","tagline":"Coach an AlignFirst spec-plan-execute or AAD workflow using a CLI wrapper around a coding-agent CLI. Use when orchestrating coding agents through AlignFirst protocols non-interactively.","description":"Read the *alignfirst* skill (`../alignfirst/SKILL.md`) and its `references/overview.md` if not already loaded.\n\n**Important: Never implement anything by yourself when you act as an AlignFirst coach. Never investigate or modify the codebase directly. Your role is to delegate and guide the agent.**\n\n# AlignFirst Coaching Guide\n\nThe CLI script is at `scripts/alignfirst-agent.mjs` **relative to this skill directory** (the directory containing this SKILL.md file). Resolve the absolute path before running it. For example, if this file is at `/home/user/.agents/skills/alignfirst-coaching/SKILL.md`, the script is at `/home/user/.agents/skills/alignfirst-coaching/scripts/alignfirst-agent.mjs`.\n\nThe script wraps a coding-agent CLI (currently `claude`) for non-interactive usage. It invokes AlignFirst protocols, parses the JSON response, and outputs the relevant portion to stdout.\n\nFor `--new` modes, the output starts with a `Session ID:` line — save it to resume the conversation later.\n\n## CLI Reference\n\n```\nnode scripts/alignfirst-agent.mjs --new --protocol <protocol> --ticket <id> [--message \"...\"]\nnode scripts/alignfirst-agent.mjs --new --message \"...\"\nnode scripts/alignfirst-agent.mjs --resume <sessionId> [--protocol <protocol>] [--message \"...\"]\n```\n\n**Flags:**\n\n| Flag | Description |\n|------|-------------|\n| `--new` | Start a new session. |\n| `--resume <id>` | Continue an existing session. |\n| `--protocol` | One of: `spec`, `plan`, `aad`, `description`, `read`, `review`, `merge`. Optional. |\n| `--ticket <id>` | Ticket ID. Required with `--new` + `--protocol`. |\n| `--message \"...\"` | Message to send. Required for `spec`, `aad`, and when no `--protocol` is given. Optional for other protocols. |\n| `--model <model>` | Optional model override. |\n\n**Key pattern — no protocol:** When no `--protocol` is given, the message is sent as-is (no AlignFirst slash command is invoked). This is used to:\n- Continue a discussion in an existing session (e.g. answering agent questions)\n- Execute an existing plan file in a new session\n- Ask the agent a question in a new session\n\n```bash\nnode scripts/alignfirst-agent.mjs --resume <sessionId> --message \"Your answer\"\nnode scripts/alignfirst-agent.mjs --new --message \"Execute the plan: \\`.plans/AB-123/A2-plan.md\\`\"\nnode scripts/alignfirst-agent.mjs --new --message \"Explain how ... works in this project. Do not implement anything. We need to talk first.\"\n```\n\n**Important:** When using `--new` without a protocol for a question or discussion (not plan execution), the agent is a coding agent and will try to implement things by default. End your message with a clear constraint, e.g.: *\"Do not implement anything. We need to talk first.\"*\n\n## Spec-Plan-Execute Workflow\n\nThe default workflow. Always start with it, except for very insignificant tasks.\n\n### Step 1 — Create a spec\n\n```bash\nnode scripts/alignfirst-agent.mjs --new --protocol spec --ticket AB-123 --message \"Description of the feature or task\"\n```\n\nThe agent investigates the codebase and responds with its findings and questions. Save the session ID from the output. There may be several back-and-forths before the agent is satisfied and writes the spec file — see [Answering agent questions](#answering-agent-questions).\n\n### Step 2 — Request a plan\n\nOnce the spec is written, request a plan in the same session:\n\n```bash\nnode scripts/alignfirst-agent.mjs --resume <sessionId> --protocol plan\n```\n\nThe agent writes a plan file (e.g. `.plans/AB-123/A2-plan.md`) and provides its path in the output. The agent rarely asks questions at this stage.\n\n### Step 3 — Execute the plan\n\nStart a **new** session to execute the plan:\n\n```bash\nnode scripts/alignfirst-agent.mjs --new --message \"Execute the plan: \\`.plans/AB-123/A2-plan.md\\`\"\n```\n\nThe agent implements the plan and writes a summary file (e.g. `.plans/AB-123/A2-plan.summary.md`), providing its path in the output.\n\n### Step 4 — Commit\n\nThe spec file contains a suggested commit message near the top. Use it to commit the changes locally.\n\n## Light Workflow (AAD)\n\nFor straightforward changes that can be done in one shot — like moving a button or tweaking a color — or for follow-up adjustments right after executing a plan. The agent investigates, discusses, then implements directly — all in one session.\n\n### Step 1 — Start an AAD session\n\n```bash\nnode scripts/alignfirst-agent.mjs --new --protocol aad --ticket AB-123 --message \"Description of the task\"\n```\n\nLike the spec workflow, the agent investigates the codebase and asks questions. Save the session ID. Answer questions the same way — see [Answering agent questions](#answering-agent-questions).\n\nOnce aligned, the agent implements the changes and writes a summary file (e.g. `.plans/AB-123/A1-AAD.summary.md`), providing its path in the output.\n\n### Step 2 — Commit\n\nThe summary file contains a suggested commit message. Commit locally as in the spec workflow.\n\n## Description\n\nGenerates a PR/MR description for work already committed. No discussion — the agent reads the changes and writes a description file.\n\n```bash\nnode scripts/alignfirst-agent.mjs --new --protocol description --ticket AB-123\n```\n\nThe agent writes a markdown file with the description and provides its path in the output.\n\n## Read (Load Context)\n\nLoads the spec and summary files for a ticket into the agent's context. Without `--message`, the agent describes what was done for the ticket. With `--message`, it loads context then processes the message in a single call — useful to ask questions about prior work.\n\n```bash\nnode scripts/alignfirst-agent.mjs --new --protocol read --ticket AB-123\nnode scripts/alignfirst-agent.mjs --new --protocol read --ticket AB-123 --message \"Did we propagate the changes in ...? Do not implement anything. We need to talk first.\"\n```\n\n## Review (Code Review)\n\nReviews the current branch against the base branch and writes a review report.\n\n```bash\nnode scripts/alignfirst-agent.mjs --new --protocol review --ticket AB-123\n```\n\nThe agent writes a review file (e.g. `.plans/AB-123/A3-review.md`) and provides its path in the output.\n\n## Merge\n\nResolves merge or rebase conflicts and summarizes the tricky resolutions. Can also start the merge when given an incoming branch.\n\nWhen conflicts are already present:\n\n```bash\nnode scripts/alignfirst-agent.mjs --new --protocol merge --ticket AB-123\n```\n\nWhen the merge has not started, pass the incoming branch via `--message`:\n\n```bash\nnode scripts/alignfirst-agent.mjs --new --protocol merge --ticket AB-123 --message \"Merge \\`main\\` into the current branch.\"\n```\n\nOn conflicts, the agent writes a summary file (e.g. `.plans/AB-123/A4-merge.summary.md`) and provides its path. On a clean merge, no summary is written.\n\n## Answering Agent Questions\n\nDuring spec and AAD sessions, the agent asks questions before proceeding. Resume the session **without a protocol** to answer:\n\n```bash\nnode scripts/alignfirst-agent.mjs --resume <sessionId> --message \"Your answer here\"\n```\n\nThere may be several back-and-forths before the agent is satisfied.\n\nThe agent often asks multiple questions at once. Answer them all in a single message, numbered to match:\n\n```bash\nnode scripts/alignfirst-agent.mjs --resume <sessionId> --message \\\n  \"1 - Explore the codebase to find out, and give me your opinion.\n2 - Is that a good design? We need the cleanest code possible.\n3 - We checked with the team: yes, it should be optional.\"\n```\n\n### Technical vs functional questions — this is critical\n\n**Technical questions** — architecture, code patterns, existing behavior, implementation details. Anything answerable by reading the code: \"Is X used elsewhere?\", \"How does Y work?\", \"Should we remove Z?\", \"What's the best approach for...?\"\n\n**Never escalate these to the user.** Push the agent to investigate and think for itself. Example responses:\n\n- `\"Explore the codebase to find out, and give me your opinion.\"`\n- `\"Do not rush. Take the time to fully understand the situation first.\"`\n- `\"What would be the most elegant and proper way to do it?\"`\n- `\"Is that a good design? We need the cleanest code possible.\"`\n- `\"If it is a better design, then yes. If you're not sure, take the time to investigate more.\"`\n- `\"Check if a similar pattern is already implemented elsewhere in the codebase.\"`\n\n**Functional or UX questions** — product behavior, user-facing decisions, business rules. These require human judgement. Escalate to your user, then relay their answer.\n\n**When in doubt**, ask the agent to explore first. Only escalate to the user if the question truly cannot be answered from the codebase.","tags":["alignfirst","coaching","paleo","agent-skills","agentic-coding","agentic-engineering"],"capabilities":["skill","source-paleo","skill-alignfirst-coaching","topic-agent-skills","topic-agentic-coding","topic-agentic-engineering"],"categories":["alignfirst"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/paleo/alignfirst/alignfirst-coaching","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add paleo/alignfirst","source_repo":"https://github.com/paleo/alignfirst","install_from":"skills.sh"}},"qualityScore":"0.489","qualityRationale":"deterministic score 0.49 from registry signals: · indexed on github topic:agent-skills · 79 github stars · SKILL.md body (8,576 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:56:45.869Z","embedding":null,"createdAt":"2026-04-18T22:12:34.979Z","updatedAt":"2026-05-18T18:56:45.869Z","lastSeenAt":"2026-05-18T18:56:45.869Z","tsv":"'-123':399,616,718,791,799,840,890,911 '/alignfirst/skill.md':39 '/home/user/.agents/skills/alignfirst-coaching/scripts/alignfirst-agent.mjs':115 '/home/user/.agents/skills/alignfirst-coaching/skill.md':110 '1':387,603,1007 '2':453,672,1019 '3':499,1031 '4':539 'aad':12,199,219,561,606,613,947 'ab':398,615,717,790,798,839,889,910 'absolut':98 'act':55 'adjust':585 'agent':22,28,75,122,269,282,339,343,408,436,446,450,476,491,521,592,627,645,649,654,701,720,749,755,842,922,942,950,981,985,1090,1205 'align':652 'alignfirst':2,6,30,37,58,76,133,251 'alignfirst-coach':1 'alreadi':45,696,880,1170 'also':868 'alway':377 'answer':268,295,445,449,638,644,648,941,962,969,992,1059,1199,1220 'answering-agent-quest':448,647 'anyth':50,317,363,810,1058 'approach':1080 'architectur':1051 'around':18 'as-i':247 'ask':280,493,632,778,951,987,1203 'back':431,976 'back-and-forth':430,975 'base':825 'bash':289,391,469,511,608,710,783,832,882,903,963,1002 'behavior':1055,1181 'best':1079 'better':1149 'branch':822,826,876,900,918 'busi':1186 'button':575 'call':775 'cannot':1218 'chang':557,564,657,704,805 'check':1033,1164 'claud':125 'clean':935 'cleanest':1028,1142 'clear':357 'cli':16,23,80,123,164 'coach':3,4,59,77 'code':21,27,121,342,817,1029,1052,1063,1143 'codebas':65,411,630,1010,1101,1175,1223 'coding-ag':20,120 'color':579 'command':253 'commit':540,547,555,673,680,682,697 'conflict':861,878,920 'constraint':358 'contain':92,544,677 'context':737,751,767 'continu':190,260 'convers':162 'creat':388 'critic':1048 'current':124,821,917 'decis':1185 'default':351,375 'deleg':71 'describ':756 'descript':183,200,401,618,689,693,708,715,727 'design':1024,1138,1150 'detail':1057 'direct':66,597 'directori':89,91 'discuss':262,334,594,699 'done':568,759 'doubt':1202 'e.g':267,359,481,530,663,847,927 'eleg':1127 'elsewher':1067,1172 'end':352 'escal':1083,1192,1210 'exampl':104,1097 'except':381 'execut':10,271,300,337,372,500,508,516,588 'exist':192,265,273,1054 'explain':308 'explor':1008,1099,1207 'face':1184 'featur':404 'file':95,107,275,443,480,529,543,662,676,709,724,743,846,926 'find':416,1012,1103 'first':322,368,815,1121,1208 'flag':181,182 'follow':583 'follow-up':582 'forth':433,978 'fulli':1117 'function':1044,1176 'generat':690 'give':1015,1106 'given':225,242,873 'good':1023,1137 'guid':73,78 'human':1190 'id':155,207,422,637 'implement':49,316,348,362,522,596,655,809,1056,1171 'import':47,323 'incom':875,899 'insignific':384 'interact':34,129 'investig':61,409,593,628,1092,1162 'invok':132,255 'json':137 'judgement':1191 'key':234 'later':163 'light':559 'like':572,622 'line':156 'load':46,736,738,766 'local':558,683 'main':914 'markdown':723 'match':1001 'may':427,972 'merg':203,856,858,871,887,893,908,913,936 'messag':171,175,180,212,213,244,293,299,307,354,400,515,548,617,681,753,764,771,800,902,912,967,998,1006 'mode':148 'model':230,232 'modifi':63 'move':573 'multipl':988 'near':549 'need':319,365,812,1026,1140 'never':48,60,1082 'new':147,168,174,184,187,210,278,287,298,306,326,394,505,514,611,713,786,794,835,885,906 'node':166,172,176,290,296,304,392,470,512,609,711,784,792,833,883,904,964,1003 'non':33,128 'non-interact':32,127 'number':999 'often':986 'one':195,570,600 'opinion':1018,1109 'option':204,226,231,1041 'orchestr':26 'output':140,150,425,489,537,670,734,855 'overrid':233 'pars':135 'pass':897 'path':99,486,534,667,731,852,932 'pattern':235,1053,1168 'plan':9,198,274,302,336,371,456,464,474,479,502,510,518,524,590 'plans/ab-123/a1-aad.summary.md':664 'plans/ab-123/a2-plan.md':303,482,519 'plans/ab-123/a2-plan.summary.md':531 'plans/ab-123/a3-review.md':848 'plans/ab-123/a4-merge.summary.md':928 'portion':143 'possibl':1030,1144 'pr/mr':692 'present':881 'prior':781 'proceed':954 'process':769 'product':1180 'project':313 'propag':803 'proper':1129 'protocol':31,134,169,179,194,211,223,229,237,240,329,395,473,612,714,787,795,836,886,907,960 'provid':484,532,665,729,850,930 'push':1088 'question':270,284,332,418,447,451,494,633,639,646,650,779,943,952,989,1045,1050,1179,1216 'rare':492 're':1155 'read':35,201,702,735,788,796,1061 'rebas':860 'refer':165 'references/overview.md':42 'relat':85 'relay':1197 'relev':142 'remov':1074 'report':831 'request':454,462 'requir':208,216,1189 'resolut':866 'resolv':96,857 'respond':413 'respons':138,1098 'resum':160,178,189,292,472,955,966,1005 'review':202,816,818,819,830,837,845 'right':586 'role':68 'rule':1187 'run':101 'rush':1112 'satisfi':438,983 'save':157,419,634 'script':81,112,117 'scripts/alignfirst-agent.mjs':84,167,173,177,291,297,305,393,471,513,610,712,785,793,834,884,905,965,1004 'see':444,643 'send':215 'sent':246 'session':154,188,193,266,279,288,421,468,506,601,607,636,948,957 'sever':429,974 'shot':571 'similar':1167 'singl':774,997 'situat':1120 'skill':38,88 'skill-alignfirst-coaching' 'skill.md':94 'slash':252 'source-paleo' 'spec':8,197,218,370,390,396,442,459,542,624,687,740,945 'spec-plan-execut':7,369 'stage':497 'start':151,185,378,503,604,869,896 'stdout':145 'step':386,452,498,538,602,671 'straightforward':563 'suggest':546,679 'summar':863 'summari':528,661,675,742,925,938 'sure':1157 'take':1113,1158 'talk':321,367,814 'task':385,406,621 'team':1036 'technic':1042,1049 'thing':349 'think':1094 'ticket':170,205,206,397,614,716,746,762,789,797,838,888,909 'time':1115,1160 'top':551 'topic-agent-skills' 'topic-agentic-coding' 'topic-agentic-engineering' 'tri':346 'tricki':865 'truli':1217 'tweak':577 'understand':1118 'usag':130 'use':14,24,258,325,552,776,1066 'user':1087,1183,1195,1213 'user-fac':1182 'ux':1178 'via':901 'vs':1043 'way':642,1130 'without':327,752,958 'work':310,695,782,1071 'workflow':13,373,376,560,625,688 'would':1123 'wrap':118 'wrapper':17 'write':440,477,526,659,706,721,828,843,923 'written':461,940 'x':1065 'y':1070 'yes':1037,1152 'z':1075","prices":[{"id":"fc3ce317-76b8-4390-b199-2220ea348dae","listingId":"dae36c73-6e75-4aeb-ba49-56cb20e3d0c6","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"paleo","category":"alignfirst","install_from":"skills.sh"},"createdAt":"2026-04-18T22:12:34.979Z"}],"sources":[{"listingId":"dae36c73-6e75-4aeb-ba49-56cb20e3d0c6","source":"github","sourceId":"paleo/alignfirst/alignfirst-coaching","sourceUrl":"https://github.com/paleo/alignfirst/tree/main/skills/alignfirst-coaching","isPrimary":false,"firstSeenAt":"2026-04-18T22:12:34.979Z","lastSeenAt":"2026-05-18T18:56:45.869Z"}],"details":{"listingId":"dae36c73-6e75-4aeb-ba49-56cb20e3d0c6","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"paleo","slug":"alignfirst-coaching","github":{"repo":"paleo/alignfirst","stars":79,"topics":["agent-skills","agentic-coding","agentic-engineering"],"license":"cc0-1.0","html_url":"https://github.com/paleo/alignfirst","pushed_at":"2026-05-17T16:54:16Z","description":"The skill of Spartan developers who love well-written code","skill_md_sha":"623917efbcc299ea4099583335051eb28a5cb193","skill_md_path":"skills/alignfirst-coaching/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/paleo/alignfirst/tree/main/skills/alignfirst-coaching"},"layout":"multi","source":"github","category":"alignfirst","frontmatter":{"name":"alignfirst-coaching","license":"CC0 1.0","description":"Coach an AlignFirst spec-plan-execute or AAD workflow using a CLI wrapper around a coding-agent CLI. Use when orchestrating coding agents through AlignFirst protocols non-interactively.","compatibility":"Requires Node.js and the Claude Code CLI"},"skills_sh_url":"https://skills.sh/paleo/alignfirst/alignfirst-coaching"},"updatedAt":"2026-05-18T18:56:45.869Z"}}