Skip to content
Forgeplan

forgeplan delete

Permanently remove an artifact from the workspace. This deletes the markdown file on disk and cascades through the LanceDB index, dropping every relation where the artifact appears as source or target.

Deletion is destructive and not reversible. Unless you are cleaning up a true mistake (e.g. a test artifact, a typo’d ID, a duplicate), you almost certainly want forgeplan deprecate or forgeplan supersede instead — both preserve decision history, which is the whole point of the methodology.

Usage

Section titled “Usage”
forgeplan delete [OPTIONS] <ID>

Arguments

Section titled “Arguments”
  <ID>  Artifact ID

Options

Section titled “Options”
      --yes      Skip confirmation
  -h, --help     Print help
  -V, --version  Print version

What it does

Section titled “What it does”
  1. Confirms the deletion interactively (skip with --yes).
  2. Removes the markdown file from .forgeplan/<kind>s/<id>.md.
  3. Deletes the artifact row from the LanceDB artifacts table.
  4. Cascade-deletes every relation in the links table where the artifact is source or target.
  5. Leaves other artifacts intact — but they may now reference a deleted ID.

Examples

Section titled “Examples”

Delete a stray Note after interactive confirmation:

Terminal window
forgeplan delete NOTE-042

Scripted delete (no prompt):

Terminal window
forgeplan delete NOTE-042 --yes

Safety: when NOT to delete

Section titled “Safety: when NOT to delete”

Do not delete an active artifact as a way to “cancel” it. The methodology treats abandoned decisions as first-class history — they remain discoverable and explain why the project went a different way.

SituationDo this instead
Decision was superseded by a newer oneforgeplan supersede <old> --by <new>
Decision is no longer relevantforgeplan deprecate <id> --reason "..."
Artifact is an orphan with no content yetDelete is fine
You created a typo’d ID (PRD-0001 instead of PRD-1)Delete is fine
Experimental Note that was never linkedDelete is fine

Rule of thumb: if anything links to the artifact, deprecate. If it’s a dead-end stub with no history, delete.

Before you delete — back up

Section titled “Before you delete — back up”

Cascade deletion of relations cannot be undone without a git restore or an earlier export. Before bulk-deleting, run:

Terminal window
forgeplan export --output backup-$(date +%Y%m%d).json

And for peace of mind:

Terminal window
cp -r .forgeplan .forgeplan-backup-$(date +%Y%m%d)

You can then forgeplan import backup.json to restore if you regret the operation. See the AGENT-ENFORCEMENT guide for why rm -rf .forgeplan is a banned shortcut.

Notes

Section titled “Notes”
  • delete does not check whether other artifacts reference the target. It is the caller’s responsibility to ensure no active decision depends on it.
  • Deleted artifacts disappear from forgeplan health, forgeplan list, and search results immediately.
  • If you deleted by mistake and have not committed yet, git checkout .forgeplan/<kind>s/<id>.md followed by forgeplan scan-import will restore the file and re-index it.

See also

Section titled “See also”