Gabriel Radureau
1c0ba8ea75
Two changes that go together: now operators can run every read-only
workflow without going through Claude. The skills (SKILL.md files)
remain the source of behaviour documentation and Claude triggers;
bin/arcodange is the human-facing entry point.
bin/arcodange:
- Bash dispatcher at the project root. Subcommands per domain:
tva {collect, collect-detail, deductible, deductible-detail, summary},
invoice {list, audit}, thirdparty {audit, audit-all},
payments {state, timeline, by-month},
templates {list, inspect},
snapshot, whoami, ping, curl, help.
- Locates the project root via `git rev-parse` so it works from any
CWD (including from a worktree).
- Per-subcommand `help` text. Unknown commands exit 2 with a hint.
- Reuses the existing per-skill scripts under .claude/skills/<name>/
scripts/ via `exec` (zero behaviour drift, full credit to the
existing tested code).
dolibarr-tva-summary:
- Composes dolibarr-tva-reconciliation (TVA collectée customer-side)
and dolibarr-tva-deductible (TVA déductible supplier-side) into a
single CA3-ready monthly summary with per-month net verdict
(TVA à reverser / crédit de TVA / équilibre) and a cumulative line.
- Live baseline: Arcodange en crédit de TVA de 223.22 € cumulé
(0 € collectée 259-1° CGI vs 223.22 € déductible).
- Exposed as `arcodange tva summary [--year|--since|--until]`.
Each existing skill's SKILL.md gets a one-line "CLI shortcut" near
the top so the human path is discoverable from any skill page.
The project root README.md gets a CLI section as the primary
operator entry point.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
88 lines
5.2 KiB
Markdown
88 lines
5.2 KiB
Markdown
---
|
||
name: dolibarr-tva-summary
|
||
description: One-shot CA3-ready monthly French TVA summary for Arcodange — composes `dolibarr-tva-reconciliation` (TVA collectée customer-side) and `dolibarr-tva-deductible` (TVA déductible supplier-side) into a single per-month report with bucket-by-bucket breakdown and a net verdict (TVA à reverser, crédit de TVA, or équilibre). Each month shows both sides with their CA3 bucket assignments (A1 / A4 / E2 for collectée; 19 / 20 / 17+24 for déductible) plus the net = collectée − déductible. Today Arcodange is in cumulative TVA credit of 223.22 € (0 € collectée under KissMetrics autoliquidation 259-1° CGI vs 223.22 € déductible on supplier invoices). Use when the user asks "résumé TVA du mois", "combien à reverser ce mois", "préparer la CA3", "crédit ou dette TVA", "synthèse TVA mensuelle". Depends on `dolibarr`, internally consumes the same endpoints as the two TVA sibling skills. SKIP for per-line audit (use the sibling skills directly), for writes (the declaration itself goes through impots.gouv.fr), and for non-Arcodange TVA regimes.
|
||
requires:
|
||
bins: ["curl", "jq", "python3"]
|
||
auth: true
|
||
---
|
||
|
||
# dolibarr-tva-summary — CA3-ready monthly TVA report
|
||
|
||
The single workflow that combines [dolibarr-tva-reconciliation](../dolibarr-tva-reconciliation/SKILL.md) (TVA collectée — customer side) and [dolibarr-tva-deductible](../dolibarr-tva-deductible/SKILL.md) (TVA déductible — supplier side) into one table per month with a net verdict.
|
||
|
||
**CLI shortcut:** `bin/arcodange tva summary [--year YYYY] [--since … --until …]`
|
||
|
||
Depends on the [dolibarr](../dolibarr/SKILL.md) base skill.
|
||
|
||
## What it computes
|
||
|
||
For each month in the window:
|
||
|
||
```
|
||
net = TVA collectée − TVA déductible
|
||
```
|
||
|
||
Then categorizes:
|
||
- `net > 0` → **TVA À REVERSER** (Arcodange doit cet écart à l'État sur la CA3 du mois)
|
||
- `net < 0` → **CRÉDIT DE TVA** (l'État doit cet écart à Arcodange — report ou remboursement)
|
||
- `net = 0` → équilibre
|
||
|
||
For each side, the output breaks down by CA3 bucket so you can transcribe directly:
|
||
- **Collectée**: A1 (domestic with TVA), A4 (autoliquidation intra-UE), E2 (export hors UE)
|
||
- **Déductible**: ligne 19/20 (20 % standard / taux réduits), ligne 17+24 (autoliquidation intra-UE), ligne 7 (import hors UE), FR exempt
|
||
|
||
## Workflow
|
||
|
||
```bash
|
||
bin/arcodange tva summary # all-time
|
||
bin/arcodange tva summary --year 2026
|
||
bin/arcodange tva summary --since 2026-01-01 --until 2026-01-31
|
||
```
|
||
|
||
Live output for the all-time window (captured at [examples/tva-summary.txt](examples/tva-summary.txt)):
|
||
|
||
```
|
||
=== 2026-01 ===
|
||
Customer side (TVA collectée) basis HT= 510.00 TVA= 0.00
|
||
E2 (export hors UE) HT= 510.00 TVA= 0.00
|
||
Supplier side (TVA déductible) basis HT= 403.45 TVA= 69.00
|
||
FR exempt / HT seulement HT= 8.43 TVA= 0.00
|
||
ligne 17+24 (autoliquidation intra-UE) HT= 50.00 TVA= 0.00
|
||
ligne 19/20 (20.0% déductible) HT= 345.02 TVA= 69.00
|
||
--- Net du mois : collectée − déductible = 0.00 − 69.00 = -69.00 → CRÉDIT DE TVA : 69.00 €
|
||
|
||
=== 2026-02 ===
|
||
Customer side (TVA collectée) basis HT= 7650.00 TVA= 0.00
|
||
E2 (export hors UE) HT= 7650.00 TVA= 0.00
|
||
Supplier side (TVA déductible) basis HT= 765.00 TVA= 153.00
|
||
ligne 19/20 (20.0% déductible) HT= 765.00 TVA= 153.00
|
||
--- Net du mois : collectée − déductible = 0.00 − 153.00 = -153.00 → CRÉDIT DE TVA : 153.00 €
|
||
|
||
=== CUMUL window=-inf → +inf ===
|
||
TVA collectée totale : 0.00
|
||
TVA déductible totale : 223.22
|
||
Net cumulé : -223.22 → CRÉDIT DE TVA cumulé : 223.22 €
|
||
```
|
||
|
||
## Reading the result for the CA3 declaration
|
||
|
||
For each month:
|
||
1. **Lignes E2 / A4 / A1** on the CA3 form ← from the customer-side breakdown (HT amounts).
|
||
2. **Lignes 19 / 20 / 17 / 24** ← from the supplier-side breakdown (TVA amounts).
|
||
3. **TVA nette** = collectée line totals − déductible line totals.
|
||
4. If credit, request reimbursement or carry forward to the next month.
|
||
|
||
Today Arcodange is in **continuous credit** because of the 259-1° CGI export posture (collectée = 0 systematically against KissMetrics) while normal operating expenses generate déductible. As long as Arcodange has only extra-EU export customers, this stays the steady state.
|
||
|
||
## When this skill stops being the right answer
|
||
|
||
- **A French B2B client is invoiced** (with TVA collectée > 0). Then the A1 bucket starts populating and the net can flip positive. Still the right skill, just different numbers.
|
||
- **A goods import** lands a customs ligne 7 entry. The deductible-line-detail breakdown will surface it but verifying matches against customs paperwork is out of scope.
|
||
- **TVA sur encaissements** (régime spécial). The current skill uses invoice date as the period anchor; encaissements would need to swap that for payment date. Not Arcodange's regime today.
|
||
|
||
## Out of scope
|
||
|
||
- **Writing the declaration on impots.gouv.fr.** Manual step always.
|
||
- **Préfinancement TVA / régime simplifié CA12.** Different aggregation cadence; could be a sibling skill if Arcodange's regime changes.
|
||
- **Other periodic taxes** (CFE, CVAE, IS). Different data sources.
|