1590 Python3 Development Workflow Port Plan Be5889de

Python3-Development Plugin: SAM Workflow Port Plan (from gitlab-runner-management)

This document is a durable execution plan for porting the “add-new-feature → implement-feature → start-task → complete-implementation” workflow (and its supporting agents/scripts) from ~/repos/gitlab-runner-management into this repository’s plugins/python3-development/ plugin, as skills (commands deprecated).

The goal is that you can stop at any checkpoint and resume later without re-deriving context.

Goals

• Port the artifact-driven, gated workflow from gitlab-runner-management into plugins/python3-development using skills + agents + hooks.
• Make plugins/python3-development self-contained (no references to ~/.claude/... files that aren’t in this repo).
• Remove/avoid reliance on plugins/python3-development/commands/ (or keep as legacy reference only, but not required for execution).

Inputs (Source of Truth)

Reference repo (ground truth)

• ~/repos/gitlab-runner-management/.claude/commands/
  • add-new-feature.md
  • implement-feature.md
  • start-task.md
  • complete-implementation.md
• ~/repos/gitlab-runner-management/.claude/agents/
  • feature-researcher.md
  • codebase-analyzer.md
  • plan-validator.md
  • context-gathering.md
  • feature-verifier.md
  • (plus any “complete-implementation phase” agents it calls: integration-checker.md, doc-drift-auditor.md, service-documentation.md, context-refinement.md, code-reviewer.md)
• ~/repos/gitlab-runner-management/.claude/skills/implementation-manager/
  • SKILL.md
  • scripts/implementation_manager.py
  • scripts/task_status_hook.py

Target plugin (where changes land)

• ./plugins/python3-development/.claude-plugin/plugin.json
• ./plugins/python3-development/skills/
• ./plugins/python3-development/agents/

Checkpoint 0 — Safety + State Capture (5 minutes)

• Run git status in this repo and record:
  • current branch
  • untracked/modified files
• Create a new working branch (recommended) for the port
• Decide whether to commit unrelated untracked files before starting

Resume point: If interrupted before Checkpoint 1, just rerun git status and continue.

Checkpoint 1 — Inventory: map “workflow components” to plugin equivalents

1A) Define the new skill set (user-invocable)

Create these skill directories under plugins/python3-development/skills/development/:

• add-new-feature/ (user-invocable)
• implement-feature/ (user-invocable)
• start-task/ (user-invocable)
• complete-implementation/ (user-invocable)

Each must have SKILL.md with:

• name: kebab-case (matches directory)
• description: include trigger keywords (“add feature”, “plan feature”, “implement feature”, etc.)
• argument-hint: modeled after the reference commands
• user-invocable: true
• Hooks (where needed), per Checkpoint 4

1B) Define support skills (non-user-invocable)

• skills/implementation-manager/ (user-invocable should be false)
  • Provides implementation_manager.py and task_status_hook.py
  • Provides documentation for JSON outputs + task file schema

1C) Define required agents (plugin-bundled)

Port agents from gitlab-runner-management/.claude/agents/ into plugins/python3-development/agents/:

• Required for planning pipeline:
  • feature-researcher.md
  • codebase-analyzer.md
  • plan-validator.md
  • context-gathering.md
• Required for completion/verification pipeline:
  • feature-verifier.md
  • integration-checker.md
  • doc-drift-auditor.md
  • service-documentation.md
  • context-refinement.md
  • code-reviewer.md (or map to existing python-code-reviewer.md if the prompts are compatible)

Resume point: If interrupted after Checkpoint 1, you should have a complete “bill of materials” list.

Checkpoint 2 — Vendor files into this repo (copy, don’t rewrite yet)

2A) Vendor the implementation-manager skill + scripts

Copy into the plugin:

• From: ~/repos/gitlab-runner-management/.claude/skills/implementation-manager/SKILL.md
  • To: plugins/python3-development/skills/implementation-manager/SKILL.md
• From: ~/repos/gitlab-runner-management/.claude/skills/implementation-manager/scripts/implementation_manager.py
  • To: plugins/python3-development/skills/implementation-manager/scripts/implementation_manager.py
• From: ~/repos/gitlab-runner-management/.claude/skills/implementation-manager/scripts/task_status_hook.py
  • To: plugins/python3-development/skills/implementation-manager/scripts/task_status_hook.py

2B) Vendor the phase agents

Copy the required .md agent files into plugins/python3-development/agents/.

2C) Vendor any templates referenced by the python3 plugin that are currently external/missing

These are known gaps in plugins/python3-development today:

• ~/.claude/templates/feature-task-template.md (referenced by old create-feature-task command docs)
• templates/test-checklist.md (referenced via @include in old command docs)
• ~/.claude/agents/python-cli-demo.py (referenced by multiple python3 docs/agents)
• ~/.claude/tools/validate_pep723.py (referenced by python3 tool registry docs)

Pick one canonical location inside plugins/python3-development/ (recommendation):

• Templates:
  • plugins/python3-development/skills/development/add-new-feature/templates/
  • plugins/python3-development/skills/testing/comprehensive-test-review/templates/
• Example code/assets:
  • plugins/python3-development/skills/python3-development/assets/
• Helper scripts:
  • plugins/python3-development/scripts/ (or skills/python3-development/scripts/)

Resume point: After Checkpoint 2, everything exists locally even if not yet wired.

Checkpoint 3 — Convert reference “commands” into plugin “skills”

For each of these reference command files:

• gitlab-runner-management/.claude/commands/add-new-feature.md
• gitlab-runner-management/.claude/commands/implement-feature.md
• gitlab-runner-management/.claude/commands/start-task.md
• gitlab-runner-management/.claude/commands/complete-implementation.md

Create a corresponding SKILL.md in the target directories from Checkpoint 1A.

Critical adaptations when converting:

• Replace references like:

  • $CLAUDE_PROJECT_DIR/.claude/skills/implementation-manager/...
  • .claude/agents/...

  with plugin-bundled equivalents (hooks/scripts should reference ${CLAUDE_PLUGIN_ROOT} where appropriate).

• Keep $ARGUMENTS usage intact.

• Keep structured phase outputs and DONE/BLOCKED signaling intact.

Resume point: After Checkpoint 3, user can invoke /add-new-feature-equivalent skills from the plugin.

Checkpoint 4 — Hook wiring (task status + activity timestamps)

Implement hook wiring equivalent to the reference repo:

• On implement-feature skill:
  • SubagentStop hook runs task_status_hook.py
• On start-task skill:
  • PostToolUse hook runs the hook script that updates LastActivity

Make sure the hook command points to the vendored script path inside the plugin. Prefer ${CLAUDE_PLUGIN_ROOT} for plugin-relative execution.

Resume point: After Checkpoint 4, the status automation works again (core “don’t get stuck” feature).

Checkpoint 5 — Update plugin manifest (plugin.json)

Update plugins/python3-development/.claude-plugin/plugin.json:

• Add the new skills:
  • ./skills/development/add-new-feature
  • ./skills/development/implement-feature
  • ./skills/development/start-task
  • ./skills/development/complete-implementation
  • ./skills/implementation-manager
• Add the new agents (individual ./agents/*.md paths)
• Decide policy for commands/:
  • Preferred: do not register commands at all (skills-only plugin)

Resume point: After Checkpoint 5, plugin installation will expose the new workflow.

Checkpoint 6 — Remove/neutralize legacy commands/ dependencies in this plugin

The existing plugins/python3-development/commands/ currently contains @include templates/... references that don’t exist in this plugin.

Choose one:

• Option A (preferred): remove commands/ from “required execution path” entirely
  • Keep the folder only as human documentation (no includes; no external references)
• Option B: fully vendor the referenced templates and keep commands working, but treat them as legacy

Resume point: After Checkpoint 6, the plugin has no dangling references.

Checkpoint 7 — Verification (don’t skip)

• Run repo linting on all touched files:
  • uv run prek run --files <changed-files...>
• Validate plugin.json is valid JSON
• Validate the skill frontmatter loads correctly (name/description/argument-hint formatting)
• Spot check that no ~/.claude/... file references remain unless intentionally kept as “optional external reference”

Resume point: After Checkpoint 7, you should be safe to ship.

Definition of Done (for this port)

• The planning/execution/verification workflow exists as skills in plugins/python3-development
• All referenced scripts/templates/examples are vendored into this repo
• No required step depends on ~/.claude/...
• Hooks update task status/timestamps the same way as the reference workflow
• uv run prek run --files ... passes for modified files