port

Files (1)

• SKILL.md

SKILL.md (first lines)

# /plumbline:port

Write a complete Plumbline port plan for the current project to a file. The plan enumerates every violation across both checks and the passes needed to make `plumbline .` return clean. Output goes to a markdown file — ready to hand off to a planner or to execute directly.

For the full reference on each phase, see `docs/plumbline-porting-guide.md` in the plugin distribution.

## What this does

1. Runs `plumbline doctor` to assess installation state.
2. Runs `plumbline .` to count violations per check.
3. Runs `plumbline patterns` to cluster the violations by shape — this is what makes the `comment-hygiene` pass concretely actionable instead of "thousands of them, good luck."
4. Writes a phase-by-phase plan to `./plumbline-port-plan.md` (or the path passed as the second arg). The plan's goal is **complete**: executing it leaves the lint clean with both checks on. The budget ratchet, which is a strategy for projects that won't do the full sweep at once, is referenced as a fallback in the porting guide, not in the plan itself.

The plan skips the **Adopt** pass when doctor reports `healthy`. It skips each check's pass when that check's count is zero. The total passes always include **Maintain** as the steady-state description.

## Run

```bash
plumbline_bin="${CLAUDE_PLUGIN_ROOT%/}/bin/plumbline"
guide_path="${CLAUDE_PLUGIN_ROOT%/}/docs/plumbline-porting-guide.md"
target="${1:-.}"
output="${2:-./plumbline-port-plan.md}"

abs_target=$(cd "$target" && pwd)
project=$(basename "$abs_target")

doctor_out=$(node "$plumbline_bin" doctor "$target" 2>&1 || true)
doctor_healthy=false
if echo "$doctor_out" | grep -q "plumbline doctor: healthy"; then
  doctor_healthy=true
fi

audit_out=$(node "$plumbline_bin" "$target" 2>&1 || true)
patterns_out=$(node "$plumbline_bin" patterns "$target" 2>&1 || true)

hygiene_count=$(echo "$audit_out" | grep -c "plumbline/comment-hygiene" || true)
citation_count=$(echo "$audit_out" | grep -c "plumbline/citation-unresolved" || true)
total=$((hygiene_count + citation_count))

{
  echo "# Plumbline port plan — $project"
  echo ""
  echo "Generated by \`/plumbline:port\`."
  echo ""
  echo "**Goal**: execute this plan and \`plumbline .\` returns clean with both checks (\`comment_hygiene\`, \`citation_resolution\`) enabled."
  echo ""
  echo "Reference: \`$guide_path\`"
  echo ""
  echo "## Current state"
  echo ""
  echo '```'
  echo "$doctor_out"
  echo '```'
  echo ""
  echo "## Backlog"
  echo ""
  echo "| Check | Count |"
  echo "| --- | --- |"
  echo "| comment-hygiene | $hygiene_count |"
  echo "| citation-unresolved | $citation_count |"
  echo "| **Total** | **$total** |"
  echo ""

  if [ "$total" -eq 0 ] && [ "$doctor_healthy" = "true" ]; then
    echo "## Result"
    echo ""
    echo "Already Plumbline-clean. Nothing to do."
    echo ""
  else
    echo "## Plan"
    echo ""

    pass=1

    if [ "$doctor_healthy" != "true" ]; then
      cat <<EOF
### Pass $pass — Adopt

- Install the plumbline plugin in this project
- Run \`/plumbline:affirm\`; commit \`.claude/rules/plumbline-cheatsheet.md\`
- Run \`/plumbline:starter .\`; review the proposed config; save as \`.plumbline.json\`; commit
- Verify: \`/plumbline:doctor\` reports \`healthy\`

EOF
      pass=$((pass + 1))
    fi

    if [ "$citation_count" -gt 0 ]; then
      cat <<EOF
### Pass $pass — \`citation-unresolved\` ($citation_count violations)

Citation tags are declared in \`.plumbline.json\`'s \`citations\` array. Each violation is a slug that does not resolve.

- Run \`/plumbline:patterns\` to cluster by tag (\`tag:@concept:\`, \`tag:@story:\`, ...).
- For each tag cluster: triage each slug — fix typos, rename to match an existing artifact, create the missing artifact, or remove the citation if the link is no longer load-bearing.

Verify: \`plumbline .\` reports zero \`citation-unresolved\` violations. Commit.

EOF
      pass=$((pass + 1))
    fi

    if [ "$hygiene_count" -gt 0 ]; then
      cat <<EOF
### Pass $pass — \`comment-hygiene\` ($hygiene_count violations)

Under plumbline's strict rule, comments are not permitted in source files except machine directives (license headers, lint suppressions, build tags), configured citation tags, and JSDoc/GoDoc comments in files carrying the \`@plumbline:allow-docstrings\` opt-in marker. Every violation listed is one of: an obvious deletion (residue, restatement, TODO, divider), a load-bearing constraint that should become an assertion / test / type / name, or a docstring on a public-API surface that warrants the opt-in marker.

Cluster shapes (from \`plumbline patterns\`):

\`\`\`
EOF
      echo "$patterns_out"
      cat <<'EOF'
```

For each cluster:

- `disallowed-prose` / `todo-marker` / `divider` / `commented-out-code` — sample 3-5, confirm the shape, bulk delete.

From fallguyconsulting/plumbline, Apache-2.0.

More from fallguyconsulting/plumbline