# Alignfirst Coaching > 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. - **Type:** Skill - **Install:** `agentstack add skill-paleo-alignfirst-alignfirst-coaching` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [paleo](https://agentstack.voostack.com/s/paleo) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** CC0-1.0 - **Upstream author:** [paleo](https://github.com/paleo) - **Source:** https://github.com/paleo/alignfirst/tree/main/skills/alignfirst-coaching ## Install ```sh agentstack add skill-paleo-alignfirst-alignfirst-coaching ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Read the *alignfirst* skill (`../alignfirst/SKILL.md`) and its `references/overview.md` if not already loaded. **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.** # AlignFirst Coaching Guide The CLI script is at `scripts/alignfirst-coaching.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-coaching.mjs`. The 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. Run the script from the directory of the project you're coaching, so the coding agent works in the right repo. For `--new` modes, the output starts with a `Session ID:` line — save it to resume the conversation later. ## CLI Reference ``` node scripts/alignfirst-coaching.mjs --new --protocol --ticket [--message "..."] node scripts/alignfirst-coaching.mjs --new --message "..." node scripts/alignfirst-coaching.mjs --resume [--protocol ] [--message "..."] ``` **Flags:** | Flag | Description | |------|-------------| | `--new` | Start a new session. | | `--resume ` | Continue an existing session. | | `--protocol` | One of: `spec`, `plan`, `aad`, `description`, `read`, `review`, `merge`. Optional. | | `--ticket ` | Ticket ID. Required with `--new` + `--protocol`. | | `--message "..."` | Message to send. Required for `spec`, `aad`, and when no `--protocol` is given. Optional for other protocols. | | `--model ` | Optional model override. | **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: - Continue a discussion in an existing session (e.g. answering agent questions) - Execute an existing plan file in a new session - Ask the agent a question in a new session ```bash node scripts/alignfirst-coaching.mjs --resume --message "Your answer" node scripts/alignfirst-coaching.mjs --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`" node scripts/alignfirst-coaching.mjs --new --message "Explain how ... works in this project. Do not implement anything. We need to talk first." ``` **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."* ## Spec-Plan-Execute Workflow The default workflow. Always start with it, except for very insignificant tasks. ### Step 1 — Create a spec ```bash node scripts/alignfirst-coaching.mjs --new --protocol spec --ticket AB-123 --message "Description of the feature or task" ``` The 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). ### Step 2 — Request a plan Once the spec is written, request a plan in the same session: ```bash node scripts/alignfirst-coaching.mjs --resume --protocol plan ``` The 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. ### Step 3 — Execute the plan Start a **new** session to execute the plan: ```bash node scripts/alignfirst-coaching.mjs --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`" ``` The agent implements the plan and writes a summary file (e.g. `.plans/AB-123/A2-plan.summary.md`), providing its path in the output. ### Step 4 — Commit The spec file contains a suggested commit message near the top. Use it to commit the changes locally. ## Light Workflow (AAD) For 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. ### Step 1 — Start an AAD session ```bash node scripts/alignfirst-coaching.mjs --new --protocol aad --ticket AB-123 --message "Description of the task" ``` Like 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). Once 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. ### Step 2 — Commit The summary file contains a suggested commit message. Commit locally as in the spec workflow. ## Description Generates a PR/MR description for work already committed. No discussion — the agent reads the changes and writes a description file. ```bash node scripts/alignfirst-coaching.mjs --new --protocol description --ticket AB-123 ``` The agent writes a markdown file with the description and provides its path in the output. ## Read (Load Context) Loads 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. ```bash node scripts/alignfirst-coaching.mjs --new --protocol read --ticket AB-123 node scripts/alignfirst-coaching.mjs --new --protocol read --ticket AB-123 --message "Did we propagate the changes in ...? Do not implement anything. We need to talk first." ``` ## Review (Code Review) Reviews the current branch against the base branch and writes a review report. ```bash node scripts/alignfirst-coaching.mjs --new --protocol review --ticket AB-123 ``` The agent writes a review file (e.g. `.plans/AB-123/A3-review.md`) and provides its path in the output. ## Merge Resolves merge or rebase conflicts and summarizes the tricky resolutions. Can also start the merge when given an incoming branch. When conflicts are already present: ```bash node scripts/alignfirst-coaching.mjs --new --protocol merge --ticket AB-123 ``` When the merge has not started, pass the incoming branch via `--message`: ```bash node scripts/alignfirst-coaching.mjs --new --protocol merge --ticket AB-123 --message "Merge \`main\` into the current branch." ``` On 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. ## Answering Agent Questions During spec and AAD sessions, the agent asks questions before proceeding. Resume the session **without a protocol** to answer: ```bash node scripts/alignfirst-coaching.mjs --resume --message "Your answer here" ``` There may be several back-and-forths before the agent is satisfied. The agent often asks multiple questions at once. Answer them all in a single message, numbered to match: ```bash node scripts/alignfirst-coaching.mjs --resume --message \ "1 - Explore the codebase to find out, and give me your opinion. 2 - Is that a good design? We need the cleanest code possible. 3 - We checked with the team: yes, it should be optional." ``` ### Technical vs functional questions — this is critical **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...?" **Never escalate these to the user.** Push the agent to investigate and think for itself. Example responses: - `"Explore the codebase to find out, and give me your opinion."` - `"Do not rush. Take the time to fully understand the situation first."` - `"What would be the most elegant and proper way to do it?"` - `"Is that a good design? We need the cleanest code possible."` - `"If it is a better design, then yes. If you're not sure, take the time to investigate more."` - `"Check if a similar pattern is already implemented elsewhere in the codebase."` **Functional or UX questions** — product behavior, user-facing decisions, business rules. These require human judgement. Escalate to your user, then relay their answer. **When in doubt**, ask the agent to explore first. Only escalate to the user if the question truly cannot be answered from the codebase. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [paleo](https://github.com/paleo) - **Source:** [paleo/alignfirst](https://github.com/paleo/alignfirst) - **License:** CC0-1.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-paleo-alignfirst-alignfirst-coaching - Seller: https://agentstack.voostack.com/s/paleo - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.