c9336941ac
Add four skills for Tempo/KSeF timesheet and invoice workflows: - check-my-timesheet: show/log the current user's Tempo time entries - timesheet-checker: audit timesheet completion across all reporters - invoice-checker: pull KSeF invoices, check contractors + MF white list - invoice-prep: summarize Tempo hours per Jira project for invoicing Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
84 lines
3.4 KiB
Markdown
84 lines
3.4 KiB
Markdown
---
|
|
name: invoice-prep
|
|
description: >
|
|
Show what to put on an invoice for a selected month by checking the user's
|
|
own Tempo timesheets. Lists every Jira project code and the total hours logged
|
|
against it. Warns if there are missing hours or days with no logged time.
|
|
TRIGGER when user asks what to put on an invoice, what to invoice, invoice
|
|
preparation, timesheet summary for invoicing, or similar phrases.
|
|
Trigger phrases: "what should I put on an invoice", "prepare my invoice",
|
|
"invoice for [month]", "what to invoice for", "check my TS for invoice".
|
|
---
|
|
|
|
# Invoice Preparation
|
|
|
|
Use this skill when someone wants to know what project codes and hours to put on their invoice for a given month. It reads their own Tempo worklogs, groups hours by Jira project, and warns about any missing time.
|
|
|
|
**In Claude Code, you run the pipeline automatically.** The user provides a month — you handle everything else.
|
|
|
|
## Prerequisites
|
|
|
|
Uses the same credentials as the timesheet-checker — no extra setup needed:
|
|
|
|
| Variable | Purpose |
|
|
|---|---|
|
|
| `TEMPO_API_TOKEN` | Fetch worklogs from Tempo |
|
|
| `JIRA_BASE_URL` | Resolve the user's account ID |
|
|
| `JIRA_EMAIL` | Identifies whose timesheets to read |
|
|
| `JIRA_API_TOKEN` | Authenticate with Jira |
|
|
|
|
All four must be present in the `.env` file in the project root.
|
|
|
|
## Extracting the month
|
|
|
|
Convert natural language to `YYYY-MM` before running:
|
|
|
|
| User says | CLI value |
|
|
|---|---|
|
|
| "last month" | Previous calendar month |
|
|
| "this month" | Current calendar month |
|
|
| "June", "June 2026" | `2026-06` |
|
|
| "May" | `2026-05` (current year) |
|
|
|
|
If no month is specified, ask: "Which month should I check? (e.g. last month, June 2026)"
|
|
|
|
## Workflow
|
|
|
|
**Step 1 — Run the script:**
|
|
|
|
```bash
|
|
python3 {SKILL_DIR}/scripts/run.py \
|
|
--month {YYYY-MM} \
|
|
--output-dir ./timesheet-output
|
|
```
|
|
|
|
This resolves the user's Jira account, fetches their Tempo worklogs for the full calendar month, groups hours by Jira project code, checks completeness against the Polish working calendar, and writes `invoice_prep_{YYYY-MM}.json` to `./timesheet-output/`.
|
|
|
|
**Step 2 — Present results.** Read the output JSON and show the user:
|
|
|
|
1. A table of project codes and hours — formatted ready to copy onto an invoice.
|
|
Include **every project in the `projects` array**. Do NOT label any project as "non-billable" or omit it from the table — the script already excludes ignored issues; everything remaining is billable:
|
|
|
|
```
|
|
| Project | Hours |
|
|
| IAA | 45.5 |
|
|
| PROJ | 22.0 |
|
|
```
|
|
|
|
Below the table, note ignored issues and their hours as a parenthetical: `(INTERNAL-1: 40h ignored per config.)` — do not mix them into the billable table.
|
|
|
|
2. The **total billable hours** from `total_billable_hours` (not `total_logged_hours`).
|
|
|
|
3. If `missing_hours > 0`: a clear warning showing:
|
|
- How many hours are missing vs the expected total for the month
|
|
- Which specific dates have no logged time (up to 10; if more, show count)
|
|
- Reminder to complete the timesheet before issuing the invoice
|
|
|
|
4. If `total_logged_hours == 0`: warn that no hours were found at all for the month.
|
|
|
|
## Guardrails
|
|
|
|
- Never fabricate or estimate hours. All data comes from Tempo.
|
|
- If `JIRA_EMAIL` is not set, stop and tell the user.
|
|
- If any script step fails, show the error and stop.
|
|
- Always remind the user that incomplete timesheets will cause Jira compliance failures when the invoice is checked.
|