publish-plan

name	publish_plan
description	publish-plan

publish-plan

Convert a plan file (release plan, feature spec, or .cursor/plans/ file) into a GitHub Discussion post written for external readers. Strips internal references and PII, rewrites for a public audience, and optionally posts via the GitHub CLI.

When to Use

Use when you have a plan in progress and want external input before execution. Pass the path to any plan document as the argument:

/publish-plan docs/releases/in_progress/v0.12.0/release_plan.md
/publish-plan .cursor/plans/some_plan.md
/publish-plan docs/feature_units/in_progress/FU-2026-01-001/FU-2026-01-001_spec.md

Optionally pass a specific question to ask readers as a second argument:

/publish-plan docs/releases/in_progress/v0.12.0/release_plan.md "Does this sync model work for your use case?"

---

Step 1: Read and Parse the Plan

1. Read the plan file at the provided path.
2. Extract the following from the document:
   • Goal / motivation: Why does this exist? What problem does it solve?
   • Approach / key decisions: What choices were made or are still open?
   • Scope boundaries: What is explicitly excluded or deferred?
   • Open questions: What is uncertain or unresolved?

---

Step 2: Strip Internal References

Remove or redact anything that should not be public:

• Full names and email addresses of individuals
• Internal Slack channels, ticket numbers, or system identifiers that leak org structure
• Pricing, cost, or revenue figures
• Internal hostnames, credentials, or environment-specific configuration values
• Agent execution notes (batch status, orchestrator output, FU dependency trees)
• Anything marked <!-- internal --> or [INTERNAL]

Do not strip:

• Feature IDs (FU-YYYY-MM-NNN) — these are useful public references
• Architecture decisions and technical rationale
• Version numbers and release IDs
• Links to public repo files or issues

---

Step 3: Draft the Discussion Post

Rewrite the extracted content into the following structure. Write in plain prose for an external developer audience. No jargon specific to the foundation framework.

## What we're building

[2-3 sentences: the problem being solved and the general approach. No implementation detail.]

## Key decisions

[3-5 bullet points: choices made or still open. Frame as "We chose X because Y" or "We're deciding between X and Y".]

## What's out of scope (for now)

[2-4 bullet points: explicit exclusions that might surprise readers or that they might assume are included.]

## Where we want input

[The specific question. One sentence. Concrete. If the user provided a question, use it here. Otherwise, derive the most useful open question from the plan.]

---

*This is a pre-execution plan. We're sharing it before we build to get early input.
Comments and questions welcome.*

Apply the content style rules:

• Complete sentences throughout
• No em dashes, no "leverage", no "seamless", no marketing language
• Active voice
• 15-20 words per sentence maximum
• No filler transitions ("Furthermore", "Moreover", "In addition")

---

Step 4: Preview and Confirm

Show the drafted post to the user and ask:

Here is the Discussion post draft:

---
[post content]
---

Options:
1. Post to GitHub Discussions now (requires gh CLI and Discussions enabled)
2. Copy to clipboard / show as output only
3. Edit — describe what to change

Wait for the user's choice before proceeding.

---

Step 5: Post to GitHub Discussions (if requested)

If the user chooses to post, use the GitHub CLI GraphQL API:

# Get the repository ID and Discussions category ID
REPO_OWNER=$(gh repo view --json owner -q '.owner.login')
REPO_NAME=$(gh repo view --json name -q '.name')

# List available discussion categories
gh api graphql -f query='
  query($owner: String!, $name: String!) {
    repository(owner: $owner, name: $name) {
      discussionCategories(first: 10) {
        nodes { id name }
      }
    }
  }
' -f owner="$REPO_OWNER" -f name="$REPO_NAME"

Use category "RFC / Plans" if it exists. If it does not exist, use the closest match ("Ideas", "General") and note to the user that a dedicated category would be better. Do not create the category automatically.

Post the discussion:

REPO_ID=$(gh api graphql -f query='
  query($owner: String!, $name: String!) {
    repository(owner: $owner, name: $name) { id }
  }
' -f owner="$REPO_OWNER" -f name="$REPO_NAME" -q '.data.repository.id')

CATEGORY_ID="<selected category id>"
TITLE="<derived from plan title or release version>"
BODY="<the drafted post content>"

gh api graphql -f query='
  mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
    createDiscussion(input: {
      repositoryId: $repoId,
      categoryId: $categoryId,
      title: $title,
      body: $body
    }) {
      discussion { url }
    }
  }
' -f repoId="$REPO_ID" -f categoryId="$CATEGORY_ID" \
  -f title="$TITLE" -f body="$BODY"

Report the Discussion URL on success.

---

Step 6: Follow-up Reminder

After posting (or outputting the draft), remind the user:

Remember to reply in the thread once a decision is made. A single note —
"We went with X because Y" — closes the loop for anyone who finds the
thread later.

---

Error Handling

gh CLI not installed or not authenticated: Output the draft post only. Include a note: "Install and authenticate the GitHub CLI (gh auth login) to post directly from this skill."

Discussions not enabled on the repository: Output the draft post only. Include a note: "Enable Discussions in the repository Settings to use the post step."

Plan file not found: Exit with: "Plan file not found: {path}. Pass the path to an existing plan document."

---

Configuration

No configuration required. The skill reads foundation-config.yaml for the repository name and remote when deriving post metadata, but falls back to gh repo view.