{"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 the claude command. Use when orchestrating coding agents through AlignFirst protocols non-interactively.","description":"Read the *alignfirst* skill (`../alignfirst/SKILL.md`) and its `references/overview.md` before doing anything else.\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 the `claude` CLI for non-interactive usage. It invokes AlignFirst protocols (`/alspec`, `/alplan`, etc.), 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`. 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 smaller tasks that don't need a formal spec and plan. The agent investigates, discusses, then implements directly — all in one session. Often used for follow-up changes after a plan has been executed.\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## 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 · 78 github stars · SKILL.md body (7,909 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-02T12:55:22.760Z","embedding":null,"createdAt":"2026-04-18T22:12:34.979Z","updatedAt":"2026-05-02T12:55:22.760Z","lastSeenAt":"2026-05-02T12:55:22.760Z","tsv":"'-123':395,608,710,783,791,832 '/alignfirst/skill.md':37 '/alplan':130 '/alspec':129 '/home/user/.agents/skills/alignfirst-coaching/scripts/alignfirst-agent.mjs':113 '/home/user/.agents/skills/alignfirst-coaching/skill.md':108 '1':383,595,914 '2':449,664,926 '3':495,938 '4':535 'aad':12,196,215,557,598,605,854 'ab':394,607,709,782,790,831 'absolut':96 'act':53 'agent':26,73,265,278,335,339,404,432,442,446,472,487,517,571,619,637,641,646,693,712,741,747,834,849,857,888,892,997,1112 'align':644 'alignfirst':2,6,28,35,56,74,127,247 'alignfirst-coach':1 'alreadi':688,1077 'alway':373 'answer':264,291,441,445,630,636,640,848,869,876,899,966,1106,1127 'answering-agent-quest':444,639 'anyth':43,48,313,359,802,965 'approach':987 'architectur':958 'around':18 'as-i':243 'ask':276,489,624,770,858,894,1110 'back':427,883 'back-and-forth':426,882 'base':817 'bash':285,387,465,507,600,702,775,824,870,909 'behavior':962,1088 'best':986 'better':1056 'branch':814,818 'busi':1093 'call':767 'cannot':1125 'chang':553,587,649,696,797 'check':940,1071 'claud':20,118 'cleanest':935,1049 'clear':353 'cli':16,78,119,161 'coach':3,4,57,75 'code':25,338,809,936,959,970,1050 'codebas':63,407,622,917,1008,1082,1130 'command':21,249 'commit':536,543,551,665,672,674,689 'constraint':354 'contain':90,540,669 'context':729,743,759 'continu':187,256 'convers':159 'creat':384 'critic':955 'current':813 'decis':1092 'default':347,371 'deleg':69 'describ':748 'descript':180,197,397,610,681,685,700,707,719 'design':931,1045,1057 'detail':964 'direct':64,576 'directori':87,89 'discuss':258,330,573,691 'done':751 'doubt':1109 'e.g':263,355,477,526,655,839 'eleg':1034 'els':44 'elsewher':974,1079 'end':348 'escal':990,1099,1117 'etc':131 'exampl':102,1004 'except':377 'execut':10,267,296,333,368,496,504,512,593 'exist':189,261,269,961 'explain':304 'explor':915,1006,1114 'face':1091 'featur':400 'file':93,105,271,439,476,525,539,654,668,701,716,735,838 'find':412,919,1010 'first':318,364,807,1028,1115 'flag':178,179 'follow':585 'follow-up':584 'formal':566 'forth':429,885 'fulli':1024 'function':951,1083 'generat':682 'give':922,1013 'given':221,238 'good':930,1044 'guid':71,76 'human':1097 'id':152,203,418,629 'implement':47,312,344,358,518,575,647,801,963,1078 'import':45,319 'insignific':380 'interact':32,123 'investig':59,405,572,620,999,1069 'invok':126,251 'json':134 'judgement':1098 'key':230 'later':160 'light':555 'like':614 'line':153 'load':728,730,758 'local':554,675 'markdown':715 'match':908 'may':423,879 'messag':168,172,177,208,209,240,289,295,303,350,396,511,544,609,673,745,756,763,792,874,905,913 'mode':145 'model':226,228 'modifi':61 'multipl':895 'near':545 'need':315,361,564,804,933,1047 'never':46,58,989 'new':144,165,171,181,184,206,274,283,294,302,322,390,501,510,603,705,778,786,827 'node':163,169,173,286,292,300,388,466,508,601,703,776,784,825,871,910 'non':31,122 'non-interact':30,121 'number':906 'often':581,893 'one':192,579 'opinion':925,1016 'option':200,222,227,948 'orchestr':24 'output':137,147,421,485,533,662,726,847 'overrid':229 'pars':132 'path':97,482,530,659,723,844 'pattern':231,960,1075 'plan':9,195,270,298,332,367,452,460,470,475,498,506,514,520,569,590 'plans/ab-123/a1-aad.summary.md':656 'plans/ab-123/a2-plan.md':299,478,515 'plans/ab-123/a2-plan.summary.md':527 'plans/ab-123/a3-review.md':840 'portion':140 'possibl':937,1051 'pr/mr':684 'prior':773 'proceed':861 'process':761 'product':1087 'project':309 'propag':795 'proper':1036 'protocol':29,128,166,176,191,207,219,225,233,236,325,391,469,604,706,779,787,828,867 'provid':480,528,657,721,842 'push':995 'question':266,280,328,414,443,447,490,625,631,638,642,771,850,859,896,952,957,1086,1123 'rare':488 're':1062 'read':33,198,694,727,780,788,968 'refer':162 'references/overview.md':40 'relat':83 'relay':1104 'relev':139 'remov':981 'report':823 'request':450,458 'requir':204,212,1096 'resolv':94 'respond':409 'respons':135,1005 'resum':157,175,186,288,468,862,873,912 'review':199,808,810,811,822,829,837 'role':66 'rule':1094 'run':99 'rush':1019 'satisfi':434,890 'save':154,415,626 'script':79,110,115 'scripts/alignfirst-agent.mjs':82,164,170,174,287,293,301,389,467,509,602,704,777,785,826,872,911 'see':440,635 'send':211 'sent':242 'session':151,185,190,262,275,284,417,464,502,580,599,628,855,864 'sever':425,881 'similar':1074 'singl':766,904 'situat':1027 'skill':36,86 'skill-alignfirst-coaching' 'skill.md':92 'slash':248 'smaller':559 'source-paleo' 'spec':8,194,214,366,386,392,438,455,538,567,616,679,732,852 'spec-plan-execut':7,365 'stage':493 'start':148,182,374,499,596 'stdout':142 'step':382,448,494,534,594,663 'suggest':542,671 'summari':524,653,667,734 'sure':1064 'take':1020,1065 'talk':317,363,806 'task':381,402,560,613 'team':943 'technic':949,956 'thing':345 'think':1001 'ticket':167,201,202,393,606,708,738,754,781,789,830 'time':1022,1067 'top':547 'topic-agent-skills' 'topic-agentic-coding' 'topic-agentic-engineering' 'tri':342 'truli':1124 'understand':1025 'usag':124 'use':14,22,254,321,548,582,768,973 'user':994,1090,1102,1120 'user-fac':1089 'ux':1085 'vs':950 'way':634,1037 'without':323,744,865 'work':306,687,774,978 'workflow':13,369,372,556,617,680 'would':1030 'wrap':116 'wrapper':17 'write':436,473,522,651,698,713,820,835 'written':457 'x':972 'y':977 'yes':944,1059 'z':982","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-02T12:55:22.760Z"}],"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":78,"topics":["agent-skills","agentic-coding","agentic-engineering"],"license":"cc0-1.0","html_url":"https://github.com/paleo/alignfirst","pushed_at":"2026-04-23T15:48:56Z","description":"The skill of Spartan developers who love well-written code","skill_md_sha":"7057de97712d50d8dcd02e9ce045534e0c02fc8a","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 the claude command. Use when orchestrating coding agents through AlignFirst protocols non-interactively.","compatibility":"Requires Node.js and the claude CLI"},"skills_sh_url":"https://skills.sh/paleo/alignfirst/alignfirst-coaching"},"updatedAt":"2026-05-02T12:55:22.760Z"}}