# us-cpa

`us-cpa` is a Python CLI plus OpenClaw skill wrapper for U.S. federal individual tax work.

## Current Milestone

Milestone 1 provides the initial package, CLI surface, skill wrapper, and test harness. Tax logic, IRS corpus download, case workflows, rendering, and review logic are not implemented yet.

## CLI Surface

```bash
skills/us-cpa/scripts/us-cpa question --question "What is the standard deduction?" --tax-year 2025
skills/us-cpa/scripts/us-cpa prepare --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa review --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa fetch-year --tax-year 2025
skills/us-cpa/scripts/us-cpa extract-docs --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa render-forms --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
skills/us-cpa/scripts/us-cpa export-efile-ready --tax-year 2025 --case-dir ~/tax-cases/2025-jane-doe
```

## Interaction Model

- `question`
  - stateless by default
  - optional case context
- `prepare`
  - requires a case directory
  - if none exists, OpenClaw should ask whether to create one and where
- `review`
  - requires a case directory
  - can operate on an existing or newly-created review case

## Planned Case Layout

```text
<case-dir>/
  input/
  extracted/
  return/
  output/
  reports/
  issues/
  sources/
```

## Output Contract

- JSON by default
- markdown available with `--format markdown`
- current milestone responses are scaffold payloads with `status: "not_implemented"`

## Scope Rules

- U.S. federal individual returns only in v1
- official IRS artifacts are the target output for compiled forms
- conflicting facts must stop the workflow for user resolution