Go Guide

/go-guide — Add a Conceptual Guide

Captures a durable concept — architectural decision, workflow rule, domain vocabulary — into the project's knowledge folder so future readers (including the same person in three months) can rediscover it without digging through commits.

---

Step 0 — Choose invocation mode

Three modes cover three lifecycles:

| Mode | Trigger | Behavior | |---|---|---| | interactive | User types /go-guide | Full flow, asks project + topic + title + text | | from-task | Skill('go-guide', mode='from-task', task_slug=…) | ship-first hook after fast-track close; suggests title/text from task context, user edits | | from-epic | Skill('go-guide', mode='from-epic', epic_slug=…) | Epic closure hook; same as from-task but scoped to whole epic |

---

Step 1 — Select project

Read aihub/projects.yml. Show numbered menu of projects. Wait for user choice or partial-name match.

Save to session context:

• {project_id} = chosen project id (slug)
• {project_path} = project's local path
• {knowledge_root} = {project_path}/project-knowledge/guides/

If {project_path} doesn't have project-knowledge/ folder — create it:

mkdir -p "{project_path}/project-knowledge/guides/"

---

Step 2 — Select topic

A topic is a stable folder grouping guides by subject (e.g. architecture, workflows, terminology, decisions). Ask the user which topic; offer existing topics first:

ls "{knowledge_root}" 2>/dev/null

Show numbered menu + 0. New topic. If user picks new — ask for slug (lowercase, hyphens). Create the folder:

mkdir -p "{knowledge_root}/{topic_slug}/"

---

Step 3 — Compose title

For interactive mode — ask user for one-line title.

For from-task / from-epic mode — propose a title derived from task/epic slug + brief. Show proposal, wait for user edit or approval.

Convert to filename slug:

"Why we chose SQLite over Postgres" → "why-sqlite-over-postgres.md"

---

Step 4 — Compose text

interactive — ask user for content. Accept multiline paste.

from-task / from-epic — propose content derived from the source material:

• Task's task.md intent + key decisions from decision-*.md files
• Report highlights ("What was notable" sections)
• Any note-*.md capturing the essence

Show the proposal for user edit before saving. Never save auto-generated content without user approval.

---

Step 5 — Write file

FILE="{knowledge_root}/{topic_slug}/{title_slug}.md"

cat > "$FILE" /dev/null || true

If {slug} / {N} unknown → hook writes empty; || true guards failure.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bearded-illirian
• Source: bearded-illirian/trailmark
• License: MIT

Install and usage instructions live in the source repository linked above.