Python REST API CLI Client Planner¶

Create a focused plan for exactly one phase of a Python CLI client project. The plan will be handed to a later process for execution.

Supplied Inputs¶

• phase: {{phase}}
• project_context: {{project_context}}
• prior_artifacts: {{prior_artifacts}}
• constraints: {{constraints}}

Operating Contract¶

1. Plan only the selected phase. Do not implement it or expand later phases in detail.
2. Inspect the existing repository and completed artifacts before proposing changes.
3. Assume the client is small unless the supplied context proves otherwise.
4. Choose the shortest path to a usable command that makes one authenticated request and presents the result clearly.
5. Reuse existing project structure and dependencies when they are adequate.
6. Distinguish verified facts, assumptions, and questions that block the selected phase.
7. Keep each step executable and verifiable, but omit ceremony that does not change implementation decisions.
8. End with a concrete artifact and a simple gate for continuing.

Simplicity Defaults¶

Use these defaults unless a verified requirement justifies more complexity:

• One installable package and one CLI entry point.
• A small command module plus a small API client module; combine them when the code remains clear.
• One synchronous API unless concurrency or an existing async application requires async behavior.
• One configuration source, usually environment variables or CLI options.
• Credentials supplied through environment variables or an established secure provider mechanism; add persistence only when users need login state across runs.
• Direct request and response handling with dictionaries; add models only for data that benefits from validation or is reused.
• Explicit timeouts, clear errors, and no automatic retries by default.
• A few focused tests around command behavior and HTTP boundaries.
• Human-readable output by default and machine-readable output only when automation is a stated use case.

Do not introduce service layers, repositories, dependency-injection containers, protocols, plugin systems, generated clients, multiple configuration profiles, credential stores, model hierarchies, or broad exception taxonomies without a concrete requirement. When proposing any of them, name the requirement and explain why a simpler function, module, or data structure is insufficient.

Phase Sequence¶

Use only the phases needed by the project. A small client may move directly from connection proof to design, implementation, verification, and release. Combine work within a phase when splitting it would add handoff cost without reducing risk.

Phase 1: Discovery (discovery)¶

Plan the minimum research needed to make one useful API request:

• Identify the intended user workflow and the first command that serves it.
• Find authoritative API documentation for one low-risk endpoint.
• Record its URL, method, authentication, inputs, response shape, errors, and relevant limits.
• Identify the supported authentication method actually needed by this client.
• Record only network, environment, and provider constraints that affect the first request.

Artifact: a short discovery brief containing sources, the first command and endpoint, request facts, authentication needs, and blocking questions.

Gate: proceed when one useful request can be attempted without guessing its protocol or credential placement.

Phase 2: Connection Proof (connection-proof)¶

Plan the smallest executable check of authentication and connectivity:

• Reuse the repository's environment and tooling.
• Add only the HTTP dependency and files required for one bounded request.
• Supply credentials without committing or logging them.
• Use explicit TLS verification and timeouts.
• Check the status, content type, and only the response fields needed by the first command.
• Capture sanitized evidence and classify failures clearly.
• Add a fake-transport check when the repository already has tests or the request logic will be retained.

Artifact: a minimal proof plan with the command, proposed file changes, focused check, real-provider procedure, and deliberate shortcuts.

Gate: proceed when the request succeeds or yields evidence of a specific external blocker.

Phase 3: Design (design)¶

Plan the smallest maintainable shape for the proven request and initial command set:

• Decide what proof code to retain, simplify, or discard.
• Define the command names, arguments, options, output, errors, and exit codes needed by known workflows.
• Choose module boundaries based on current code size and change pressure, starting with command and API client modules.
• Decide HTTP client lifecycle, authentication injection, configuration precedence, and error handling.
• Add credential persistence, structured models, pagination, retries, machine-readable output, or async behavior only when required.
• Identify the smallest production endpoint set and a consistent way to add the next command.

Artifact: a concise design note containing the command contract, proposed files, dependency choices, request flow, and justified departures from the simplicity defaults.

Gate: proceed when an implementer can build the initial commands without inventing user-visible behavior or unnecessary layers.

Phase 4: Implementation (implementation)¶

Plan vertical slices that produce working commands:

• Establish or adjust the package and CLI entry point only as needed.
• Implement configuration and authentication for the selected provider method.
• Implement the shared request behavior and first endpoint directly.
• Add commands one at a time, including presentation and stable exit behavior.
• Add focused tests beside each slice using fake HTTP responses and isolated configuration.
• Validate installation, help output, success, and the most likely failure paths after each slice.

Artifact: an ordered implementation plan naming files, changes, checks, and completion criteria for each command-sized slice.

Gate: proceed when the initial command contract works locally with deterministic tests.

Phase 5: Verification (verification)¶

Plan proportionate confidence checks for the completed client:

• Map each command's main success and error behavior to a focused test or manual check.
• Cover authentication rejection, timeout, malformed provider data, and any provider behavior the client handles specially.
• Verify real-provider behavior in a controlled environment without exposing credentials.
• Check installation, command help, output streams, exit codes, and cleanup.
• Add broader platform, concurrency, security, or end-to-end testing only when the supported environments or risk justify it.

Artifact: a compact verification matrix with automated checks, controlled real-provider checks, gaps, and pass criteria.

Gate: proceed when the supported workflows pass and remaining gaps have explicit dispositions.

Phase 6: Release Readiness (release-readiness)¶

Plan the final simplification and release checks:

• Remove proof-only code, unused dependencies, and abstractions unsupported by current requirements.
• Verify packaging, installation, help, core workflows, errors, and credential handling.
• Ensure documentation covers setup, authentication, examples, and troubleshooting actually needed by users.
• Run the repository's lint, type, test, build, and package smoke checks as applicable.
• Record blockers, deferred work, versioning, and release evidence.

Artifact: a release checklist with simplification changes, verification commands, documentation work, blockers, and sign-off criteria.

Gate: release when supported workflows have evidence of success and no unresolved blocker remains.

Complexity Triggers¶

Expand the design only when the context establishes one of these triggers:

• OAuth or another interactive credential lifecycle requires callbacks, refresh, revocation, or secure persistence.
• Multiple accounts, profiles, environments, or configuration sources are user requirements.
• Many endpoints share enough behavior that resource modules or models remove demonstrated duplication.
• Pagination, streaming, bulk operations, rate limits, or mutating retries affect correctness.
• Both human and stable machine-readable output are supported contracts.
• The client is a reusable library as well as a CLI.
• Concurrent use, plugins, long-running processes, or multiple platforms create lifecycle constraints.
• Security, compliance, or release policy requires dedicated review or evidence.

For each applicable trigger, add only the work it necessitates. Do not import the rest of a large-client architecture with it.

Planning Method¶

For the selected phase:

1. State the phase objective for the supplied project.
2. Summarize the verified inputs that affect this phase.
3. List only assumptions and open questions that could change the plan.
4. Identify the specific files or provider documentation execution must inspect.
5. Provide ordered steps with concrete actions, expected changes, and focused checks.
6. Call out any departure from the simplicity defaults and tie it to a complexity trigger.
7. Define acceptance criteria, the phase artifact, and the next gate.

Output Contract¶

Return these sections in order:

1. Phase Objective
2. Verified Inputs
3. Blocking Assumptions and Questions
4. Ordered Plan
5. Validation
6. Acceptance Criteria and Handoff

Keep the response proportional to the project. For a simple client, prefer a short plan with a handful of steps over a comprehensive architecture document.

Quality Rules¶

1. Produce a plan, not the implementation or final design artifact.
2. Use known project-specific names and paths; mark proposed paths clearly.
3. Prefer repository evidence and authoritative provider documentation over generic assumptions.
4. Include negative paths and security constraints only where they affect the selected phase.
5. Avoid future-phase decisions unless they constrain current work.
6. Do not claim a gate has passed; define the evidence needed to pass it.
7. Treat unnecessary files, dependencies, interfaces, and process as defects in the plan.