chore(docs): delete plans and superpower stuff

[rh-hemartin]

Summary

Remove plans from the docs. If I remember correctly we discussed this at some point but I'm not sure why they are still here. cc @ralphbean

Related Issue

No one for now, waiting on input.

Changes

• Delete docs/plans/
• Delete docs/superpowers/
• Add both to .gitignore

Testing

• make lint passes (stage changes first, then run)
• Tests added/updated for new or modified logic

Checklist

• PR title follows Conventional Commits (correct type, ! for breaking changes)
• Commits are signed off (DCO) — human and human-directed agent sessions only
• I wrote this contribution myself and can explain all changes in it

[qodo-code-review]

PR Summary by Qodo

Remove plans/superpowers docs and ignore those directories

📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Delete planning/spec documents under "docs/plans/" and "docs/superpowers/".
• Update ".gitignore" to prevent those directories from being reintroduced.

Diagram

graph TD
Dev(["Contributor"]) --> Git["Git tracking"] --> Ignore[".gitignore"]
Ignore -. "ignore" .-> Plans["docs/plans/"]
Ignore -. "ignore" .-> Super["docs/superpowers/"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Archive docs under a dedicated "docs/archive/" folder

• ➕ Keeps historical context available in-repo
• ➕ Avoids breaking existing deep links (with redirects or stubs)
• ➖ Still ships/retains potentially stale content unless excluded from publishing
• ➖ Requires additional organization and possibly docs-site config changes

2. Move plans/specs to a separate repository/wiki

• ➕ Separates long-form planning from product documentation
• ➕ Avoids cluttering this repo while preserving history
• ➖ Adds discovery/maintenance overhead
• ➖ Cross-repo links and permissions can be harder to manage

Recommendation: If these documents are intentionally deprecated and should not be discoverable, outright deletion is the simplest and lowest-maintenance option; adding the directories to .gitignore reinforces that decision. If there’s any chance they’ll be referenced for historical context, prefer an explicit archive location (or separate repo) over ignoring the paths entirely.

Files changed (1) +2 / -1

Other (1) +2 / -1

.gitignoreIgnore removed docs directories +2/-1

Ignore removed docs directories

• Removes the narrow ignore rule for "docs/superpowers/plans/*.md" and replaces it with directory-level ignores for "docs/plans" and "docs/superpowers" to keep those paths out of version control going forward.

.gitignore

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 10:03 AM UTC · Ended 10:12 AM UTC
Commit: fde5bb2 · View workflow run →

[github-actions]

Site preview

Preview: https://f0100bfe-site.fullsend-ai.workers.dev

Commit: 93563a017ed0198ddcf566d1f89f09fb7713c92a

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Broken plans doc links ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

This PR deletes docs under docs/plans/, but multiple ADRs, docs, and a CLI comment still reference
those paths, leaving dead links and stale guidance. Readers following the references will hit
missing files and any link-check step may fail.

Code

docs/plans/universal-harness-access.md[L1-3]

-# Universal Harness Access
-
-## Problem Statement

Relevance

●●● Strong

Team routinely fixes broken/stale doc cross-references after moves/deletions to avoid dead links.

PR-#601
PR-#2009
PR-#2743

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The repository still contains multiple references to files under docs/plans/ even though this PR
deletes those plan documents (see diff pointer).

docs/ADRs/0036-agent-execution-sandbox.md[204-214]
docs/ADRs/0038-universal-harness-access.md[209-216]
docs/ADRs/0038-universal-harness-access.md[380-383]
docs/ADRs/0044-deprecate-per-org-installation-mode.md[352-357]
docs/ADRs/0064-deprecate-customized-directory-overlay.md[85-87]
docs/problems/gitlab-implementation.md[3-9]
internal/cli/run.go[85-88]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
This PR removes the `docs/plans/` documents, but multiple remaining documents and a source comment still link to those deleted plan files. These references should be updated to point to the correct replacement (e.g., ADR sections, an archived location) or removed.

## Issue Context
Examples of remaining references include ADRs pointing at `../plans/...` and a CLI comment pointing at `docs/plans/agent-extraction-to-agents-repo.md`.

## Fix Focus Areas
- docs/ADRs/0036-agent-execution-sandbox.md[204-214]
- docs/ADRs/0038-universal-harness-access.md[209-216]
- docs/ADRs/0038-universal-harness-access.md[380-383]
- docs/ADRs/0044-deprecate-per-org-installation-mode.md[352-357]
- docs/ADRs/0045-forge-portable-harness-schema.md[703-712]
- docs/ADRs/0064-deprecate-customized-directory-overlay.md[85-87]
- docs/problems/gitlab-implementation.md[3-9]
- internal/cli/run.go[85-88]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Broken superpowers doc links ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

This PR deletes docs/superpowers/, but existing docs and web/admin documentation still link to
specific superpowers spec documents. Those references will become dead links for contributors
reading the docs.

Code

docs/superpowers/specs/2026-04-09-site-cloudflare-pages-design.md[L1-4]

-# Design: Documentation site on Cloudflare Workers (static assets, PR previews, fork-safe CI)
-
-Date: 2026-04-09
-Status: Draft (brainstorm consolidated)

Relevance

●●● Strong

Precedent favors updating docs to match current layout and prevent dead links after doc
restructuring.

PR-#242
PR-#2009
PR-#2743

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Docs still contain links into docs/superpowers/specs/..., while this PR deletes those target files
(see diff pointer).

docs/web-admin-deployment.md[7-12]
web/admin/README.md[48-51]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR removes `docs/superpowers/`, but some remaining documentation still links into `docs/superpowers/specs/...`. Those links should be removed, updated to a new location, or replaced with an alternative canonical doc.

## Issue Context
These links are in content likely read by contributors working on the web admin and deployment docs.

## Fix Focus Areas
- docs/web-admin-deployment.md[7-12]
- web/admin/README.md[48-51]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:13 AM UTC · Completed 10:28 AM UTC
Commit: 491daed · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [stale-reference] docs/ADRs/0038-universal-harness-access.md:167 — Line 167 contains "See implementation plan lines 1007-1014 for the required re-verification code." This references specific line numbers in the deleted file docs/plans/universal-harness-access.md. The PR cleans up three other references to this plan file in the same ADR (lines 209, 310, 382) but misses this one.
  Remediation: Remove the sentence from line 167. The surrounding text already describes the cache re-verification requirement; the sentence adds only a cross-reference to deleted content.

Previous run

Review

Findings

High

• [stale-reference] docs/ADRs/0067-gitlab-cron-polling-event-dispatch.md:299 — ADR 0067 references ../plans/gitlab-cron-polling-implementation.md in three locations (lines 299, 565, 575). This PR deletes the file but does not update ADR 0067, creating broken links.
  Remediation: Remove the three references and update the surrounding text.

• [adr-violation] docs/plans/ — The deleted directory contains implementation plans referenced by accepted ADRs (0036, 0038, 0044, 0045, 0064). The PR updates those ADRs to remove inline links, but does not document the decision to retire implementation plans from the repository's documentation architecture.
  Remediation: Consider creating an ADR or amendment documenting this architectural change.

Medium

• [missing-authorization] — Non-trivial change (40+ files, 16,826 deletions) lacks a linked issue. PR body states "No one for now, waiting on input."
  Remediation: Create a GitHub issue proposing the deletion and link it to this PR.

• [scope-creep] .gitignore — The .gitignore expands from docs/superpowers/plans/*.md to ignoring entire docs/plans and docs/superpowers/ directories. While consistent with the deletion, this represents an undocumented policy preventing re-creation of these directories.

Low

• [inconsistent-formatting] .gitignore:25 — docs/plans lacks a trailing slash while docs/superpowers/ has one. All other directory patterns in this file use trailing slashes.
  Remediation: Change to docs/plans/.

---

Labels: PR deletes documentation directories (docs/plans/, docs/superpowers/) and updates references across ADRs, code comments, and website config

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

[waynesun09]

One more finding that doesn't have a diff-anchorable line (none of the files below are touched by this PR):

[MEDIUM] Companion implementation-plan docs deleted with no archive, while ADRs 0057, 0058, and 0067 still normatively delegate detail to them

None of these three ADRs are touched by this PR, but they still explicitly point readers at the plan docs being deleted here:

• docs/ADRs/0057-repos-management.md:96-98 — "Manifest schema, field resolution semantics, subcommand specifications, and implementation details are in the repos management plan..."
• docs/ADRs/0058-agent-registration.md:76-77 — "See the implementation plan for phasing, schema details, CLI behavior, and migration mechanics."
• docs/ADRs/0067-gitlab-cron-polling-event-dispatch.md:298-300,563-565 — "Detailed implementation guidance ... is in the companion document: Implementation plan: GitLab cron-polling."

Suggestion: for these three, either add a short amendment noting the companion plan was retired (with date/PR reference) and inline a short summary in place of the delegating prose — matching the treatment already given to 0036/0038/0044/0045/0064 — or move the docs to an archived, non-lint-checked location instead of hard-deleting content still cited as the ADR's source of truth.

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 8:31 AM UTC · Ended 8:48 AM UTC

Commit: 93563a0 · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Superseded by updated review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:31 AM UTC · Completed 8:48 AM UTC

Commit: 93563a0 · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 12:53 PM UTC · Completed 1:07 PM UTC

Commit: 93563a0 · View workflow run →

[fullsend-ai-retro]

Retro: PR #5972 — delete plans and superpower docs

Workflow: Human-authored PR by rh-hemartin deleting docs/plans/ and docs/superpowers/ (56 files, -16,847 lines). Review agent ran 3 times (1 cancelled on force-push, 2 successful). No code/fix/triage agents involved.

What went well

• Review agent Run 2 (commit 491daed) correctly identified stale references in ADR 0067 — 3 remaining ../plans/gitlab-cron-polling-implementation.md links the author missed. Flagged as HIGH, verdict request-changes.
• Challenger sub-agent correctly debunked 2 false positives from the correctness sub-agent that were based on base-branch disk state rather than PR head.
• Re-review anchoring worked well in Run 3 — the orchestrator verified Run 2's findings were addressed before dispatching sub-agents, narrowing scope appropriately.
• Run 3 found the remaining stale reference at docs/ADRs/0038-universal-harness-access.md:167 ("See implementation plan lines 1007-1014..."), which was a genuine MEDIUM finding.

Coverage gap

The human reviewer (waynesun09's comment) ran make lint-all and found 14 broken links via lychee across ADRs 0048, 0057, 0058, 0062, 0067, and docs/architecture.md. The review agent's Run 2 only found ADR 0067's broken links. Root cause: the docs-currency sub-agent searched for docs/plans/ and docs/superpowers/ patterns, but ADR files in docs/ADRs/ reference those paths as ../plans/... (relative). The absolute-path grep missed relative-path references. See proposal below.

Merged with known defect

The stale reference at docs/ADRs/0038-universal-harness-access.md:167 was flagged by the review agent in Run 3 as MEDIUM and the requires-manual-review label was applied, but the PR was approved and merged without addressing it.

Evidence for existing issues (no new proposals filed)

• Review agent docs-currency sub-agent should verify that script and file references in documentation are linked or resolvable agents#528 and Review agent should search all documentation files for related stale references when detecting documentation drift #3932: The incomplete coverage of stale references across docs is evidence that the docs-currency sub-agent's search breadth needs improvement — both issues propose exactly this.
• Review agent should catch all findings in the first pass to reduce rework cycles #1582: The review agent missed findings in its first pass (ADRs 0048, 0057, 0058, 0062) that could have been caught, requiring the human reviewer to catch them.
• Review agent should alert when human approves with unresolved Medium+ findings #2099 and Review agent should carry forward unresolved medium+ findings across commit iterations #4956: The remaining MEDIUM finding at ADR 0038:167 was merged without being fixed — evidence for the governance gap these issues propose to close.
• Review orchestrator should skip code-analysis sub-agents for deletion-only PRs agents#666: For this docs-deletion PR, the security and style-conventions sub-agents added minimal value. Total review cost was ~$8.56 across two successful runs.

Proposals filed

• Docs-currency sub-agent should search relative path variants when checking for references to deleted files (in fullsend-ai/agents)