Manage Files Skill

Generic file operations for plan directories. Provides basic CRUD operations for any file within a plan directory.

What This Skill Provides

• Generic file read/write/remove operations
• Directory listing and creation
• File existence checking
• Plan directory create-or-reference (atomic check/create)
• No content validation (caller provides complete content)

When to Activate This Skill

Activate this skill when:

• Reading or writing arbitrary files in a plan directory
• Creating subdirectories within a plan
• Listing plan contents
• Checking if files exist

Note: For typed plan documents (

request.md

solution_outline.md

pm-workflow:manage-plan-documents

Storage Location

Files are stored in plan directories:

.plan/plans/{plan_id}/
  request.md
  solution_outline.md
  config.toon
  references.toon
  status.toon
  tasks/

Operations

Script:

pm-workflow:manage-files:manage-files

read

Read file content from a plan directory.

python3 .plan/execute-script.py pm-workflow:manage-files:manage-files read \
  --plan-id {plan_id} \
  --file notes.md

Output: Raw file content (no wrapping)

write

Write content to a file in a plan directory.

python3 .plan/execute-script.py pm-workflow:manage-files:manage-files write \
  --plan-id {plan_id} \
  --file request.md \
  --content "# Request Title

Task description with multiline content.

## Section

More content here..."

Parameters:

• --plan-id

  (required): Plan identifier

• --file

  (required): Relative file path within plan directory

• --content

  : Content to write (mutually exclusive with

  --stdin

  )

• --stdin

  : Read content from stdin instead of

  --content

Note: The

--content

--stdin

Output: Prints "Created: {path}" to stderr, exit code 0 on success

remove

Remove a file from a plan directory.

python3 .plan/execute-script.py pm-workflow:manage-files:manage-files remove \
  --plan-id {plan_id} \
  --file old-file.md

Output: Confirmation message to stderr, exit code 0 on success

list

List files in a plan directory.

python3 .plan/execute-script.py pm-workflow:manage-files:manage-files list \
  --plan-id {plan_id} \
  [--dir subdir]

Output: Simple file listing, one per line

exists

Check if a file exists.

python3 .plan/execute-script.py pm-workflow:manage-files:manage-files exists \
  --plan-id {plan_id} \
  --file config.toon

Output: Exit code 0 if exists, 1 if not

mkdir

Create a subdirectory in a plan directory.

python3 .plan/execute-script.py pm-workflow:manage-files:manage-files mkdir \
  --plan-id {plan_id} \
  --dir requirements

Output: Confirmation message to stderr, exit code 0 on success

create-or-reference

Create a plan directory if it doesn't exist, or reference an existing one. This is an atomic operation that replaces the two-step pattern of listing plans and checking for conflicts.

python3 .plan/execute-script.py pm-workflow:manage-files:manage-files create-or-reference \
  --plan-id {plan_id}

Output (TOON format):

When plan is newly created:

status: success
plan_id: my-feature
action: created
path: /path/to/.plan/plans/my-feature

When plan already exists:

status: success
plan_id: my-feature
action: exists
path: /path/to/.plan/plans/my-feature
current_phase: refine
domain: java

Use case: Called by plan-init to atomically check/create plan directories.

delete-plan

Delete an entire plan directory. Used when user selects "Replace" for an existing plan during plan-init.

python3 .plan/execute-script.py pm-workflow:manage-files:manage-files delete-plan \
  --plan-id {plan_id}

Output (TOON format):

On success:

status: success
plan_id: my-feature
action: deleted
path: /path/to/.plan/plans/my-feature
files_removed: 5

On error (plan not found):

status: error
plan_id: my-feature
error: plan_not_found
message: Plan directory does not exist: /path/to/.plan/plans/my-feature

Use case: Called by plan-init when user selects "Replace" to delete existing plan before creating new one. See

pm-workflow:phase-1-init/standards/plan-overwrite.md

Scripts

pm-workflow:manage-files:manage-files

python3 .plan/execute-script.py pm-workflow:manage-files:manage-files {subcommand} --help

Key Design Principles

1. plan_id only - Never pass full paths, script resolves base via

   base_path()

2. Relative file paths -

   --file

   accepts relative paths within plan dir (e.g.,

   requirements/REQ-001.toon

   )
3. Generic file operations - Not domain-specific (no parse-plan, write-config)
4. Plain output -

   read

   returns raw content; mutations return minimal status
5. No validation - Caller provides complete content; no content validation

Validation Rules

..

Error Handling

status: error
plan_id: my-feature
file: nonexistent.md
error: file_not_found
message: File does not exist

suggestions[2]:
- Check file name spelling
- Use list subcommand to see available files

Integration Points

With Domain Skills

Domain-specific skills (manage-config, manage-references, manage-lifecycle) may use this skill for basic file operations, or import shared libraries directly.

With Orchestration Skills

Plan orchestration skills (plan-init, solution-outline, task-plan, plan-execute) use this skill for generic file I/O.

Relationship to Domain Skills