Setup Wizard

This skill guides users through interactive initial setup of shinkoku. It generates the configuration file (

shinkoku.config.yaml

) and initializes the database.

Step 0: Verify CLI Installation

Check if the

shinkoku

command is available.

Run
```
shinkoku --version
```

If the command does not exist: Install it by running

uv tool install git+https://github.com/kazukinagata/shinkoku

If the command exists: Update to the latest version by running
```
uv tool upgrade shinkoku
```

Step 1: Check Existing Configuration

Read the

shinkoku.config.yaml

in the current working directory (CWD) using the Read tool.

If the file exists: Display its content and confirm if the user wants to update it. Exit the skill if no update is needed.
If the file does not exist: Start the setup wizard.

Step 2: Collect Basic Settings

Confirm the following items using the AskUserQuestion tool:

2-1. Target Tax Year

```
tax_year
```
: The target year for final tax return (default: 2025)

2-1b. Presence of Business Income

```
has_business_income
```
: Whether the user has business income (including side jobs) (true / false)

If there is no business income, skip the following steps:

2-2 (Invoice Registration Number)
2.6-3 (Business Address)
2.7 (Business Information)
Questions about return type (blue/white) and bookkeeping method in 2.8 (not required if only salary income)

2-2. Qualified Invoice Issuer Registration Number (Only if there is business income)

```
invoice_registration_number
```
: Number starting with T followed by 13 digits (optional, can be skipped)

Step 2.5: Collect Taxpayer Information

Confirm the following items step by step using the AskUserQuestion tool. All items are optional (can be skipped), but they are used for inputting data into the final tax return preparation corner and determining personal deductions.

2.5-1. Full Name

```
taxpayer.last_name
```
: Last name
```
taxpayer.first_name
```
: First name
```
taxpayer.last_name_kana
```
: Last name (in katakana)
```
taxpayer.first_name_kana
```
: First name (in katakana)

2.5-2. Basic Information

```
taxpayer.gender
```
: Gender (male / female)
```
taxpayer.date_of_birth
```
: Date of birth (YYYY-MM-DD)
```
taxpayer.phone
```
: Phone number
```
taxpayer.relationship_to_head
```
: Relationship to the head of household (self/wife/husband/child, etc.)

2.5-3. My Number

```
taxpayer.my_number
```
: 12-digit My Number (Note — stored in config, but never displayed in tool outputs or logs)

2.5-4. Status Related to Personal Deductions (Optional)

```
taxpayer.widow_status
```
: Widow/single parent status (none / widow / single_parent)
```
taxpayer.disability_status
```
: Disability status (none / general / special)
```
taxpayer.working_student
```
: Whether the user qualifies as a working student (true / false)

Step 2.6: Collect Address Information

2.6-1. Home Address

```
address.postal_code
```
: Postal code
```
address.prefecture
```
: Prefecture
```
address.city
```
: City/ward/town/village
```
address.street
```
: Street address
```
address.building
```
: Building name and room number (optional)

2.6-2. Address as of January 1 (Only if different from home address)

```
address.jan1_address
```
: Address as of January 1 (used to determine the municipality for resident tax)

2.6-3. Business Address (Only if there is business income and different from home address)

business_address.postal_code

business_address.building

Step 2.7: Collect Business Information

Confirm these items only if there is business income.

```
business.trade_name
```
: Trade name
```
business.industry_type
```
: Industry type
```
business.business_description
```
: Business description
```
business.establishment_year
```
: Year of establishment

Step 2.8: Confirm Filing Method

Confirm the following items in order and automatically determine the blue return special deduction amount.

Collected Items

```
filing.submission_method
```
: Submission method (e-tax / mail / in-person)
- If mail / in-person is selected:
  You can use the bookkeeping and tax calculation functions of this plugin, but the automatic input to the final tax return preparation corner (the
  /e-tax
  skill) is only available for e-Tax submissions. You will need to manually input the data into the preparation corner.
- No notification is needed if e-tax is selected (full support provided)
```
filing.return_type
```
: Return type (blue / white) — Only ask this if there is business income (skip if no business income)
- If white is selected:
  
  White return is supported. The balance sheet corner uses the income and expense breakdown sheet. Note that the bookkeeping function is designed based on double-entry bookkeeping, so the level of bookkeeping will exceed what is required for white returns.
- No notification is needed if blue is selected
```
filing.tax_office_name
```
: Name of the competent tax office

Automatic Determination Flow for Blue Return Special Deduction

return_type

blue

, determine the deduction amount using the following flow:

Ask about the bookkeeping method (double-entry bookkeeping / simplified bookkeeping)
If simplified bookkeeping → set
```
simple_bookkeeping: true
```
, deduction amount = 100,000 JPY
If double-entry bookkeeping:
- If e-Tax submission (
```
submission_method: e-tax
```
  ) → deduction amount = 650,000 JPY (regardless of
```
electronic_bookkeeping
```
  )
- If paper submission (
```
submission_method: mail
```
  or
```
in-person
```
  ) → ask about
```
electronic_bookkeeping
```
  - true
    (with excellent electronic bookkeeping storage) → deduction amount = 650,000 JPY
  - false
    → deduction amount = 550,000 JPY
Display the determination result to the user for confirmation

Related Fields

```
filing.blue_return_deduction
```
: Blue return special deduction amount (automatically determined, can also be specified manually)
- 650,000: Double-entry bookkeeping + (e-Tax submission or electronic bookkeeping storage) + filed by deadline
- 550,000: Double-entry bookkeeping + paper submission + filed by deadline (no e-Tax/electronic bookkeeping storage)
- 100,000: Simplified bookkeeping or filed after deadline
```
filing.simple_bookkeeping
```
: Whether simplified bookkeeping is used (true / false, default: false)
```
filing.electronic_bookkeeping
```
: Whether excellent electronic bookkeeping storage is available (true / false). Not required for e-Tax submissions (e-Tax alone is sufficient for the 650,000 JPY deduction)

Step 2.9: Confirm Important Matters Affecting Deductions and Filing (Mandatory)

The following items significantly impact income tax and resident tax amounts, so all items must be confirmed. Obtain an explicit response, including if the item is not applicable. Do not proceed to the next step without confirmation.

2.9-1. Family Composition (Spouse / Dependents)

Confirm the following and save to config. Details (income amount, disability status, etc.) are registered using the

/income-tax

skill.

```
family.has_spouse
```
: Whether the user has a spouse (true / false)
- If true:
  - Confirm the spouse's approximate annual income to determine eligibility for spouse deduction/special spouse deduction
  - Income ≤ 480,000 JPY → Spouse deduction; 480,000 - 1,330,000 JPY → Special spouse deduction
  - Whether the spouse is a full-time business employee: Spouses receiving salaries as blue return full-time business employees are not eligible for spouse deduction
```
family.has_dependents
```
: Whether the user has dependents (true / false)
- If true: Confirm the number of dependents and their overview (children / parents, etc.)
- Include children under 16: Although they are not eligible for dependent deduction, they are required for non-taxable determination and flat-rate tax determination for resident tax, so must be listed in the second table of the tax return "Matters related to resident tax"
- Exclude full-time business employees: Blue return full-time business employees and white return full-time business employees do not qualify as dependents
```
family.dependent_count
```
: Number of dependents (including those under 16)

My Number of spouse and dependents is collected in Step 1.5 of the
/income-tax
skill.

2.9-2. Housing Loan Deduction

```
housing_loan.applicable
```
: Whether housing loan deduction applies (true / false)
- If true:
  - housing_loan.first_year
    : Whether it is the first year (true / false)
  - First year: Create a calculation statement in Step 3.7 of
    /income-tax
    (additional documents are required)
  - From the second year onward: No additional procedures are generally required in the final tax return if the deduction was applied in year-end adjustment

2.9-3. Estimated Tax

```
estimated_tax.applicable
```
: Whether estimated tax is applicable (true / false)
- Criteria: If the declared tax amount in box ㊺ of the previous year's final tax return is 150,000 JPY or more → Estimated tax applies
- If true:
  - estimated_tax.amount
    : Total estimated tax amount (1st installment + 2nd installment, in JPY as integer)
  - If a reduction application was submitted, enter the amount after reduction

2.9-4. Name of Head of Household (If not the user)

relationship_to_head

in Step 2.5-2 is not "self":

```
taxpayer.household_head_name
```
: Confirm the name of the head of household (required for the tax return)

Step 3: Path Settings

Confirm the following paths. Present default values and use them if no changes are requested.

```
db_path
```
: Path to the database file (default:
```
./shinkoku.db
```
)
```
output_dir
```
: Output directory for progress files, etc. (default:
```
./output
```
)

Step 4: Set Document Directories (Optional)

Confirm whether to set up the following directories. Can be skipped.

```
invoices_dir
```
: Directory for invoice PDFs, etc.
```
withholding_slips_dir
```
: Directory for withholding slips
```
receipts_dir
```
: Directory for receipts
```
bank_statements_dir
```
: Directory for bank statement CSVs
```
credit_card_statements_dir
```
: Directory for credit card statement CSVs
```
deductions_dir
```
: Directory for deduction-related documents
```
past_returns_dir
```
: Directory for past final tax return data

Step 5: Preview and Save Configuration

Display a preview of the collected settings in YAML format
Obtain user confirmation
Save
```
shinkoku.config.yaml
```
to the CWD using the Write tool

Follow this YAML template:

yaml

# shinkoku user configuration file
# Can be generated interactively using the /setup skill.

# Target tax year
tax_year: {tax_year}

# Presence of business income (including side jobs)
has_business_income: {has_business_income}

# Path to database file
db_path: {db_path}

# Output directory for progress files, etc.
output_dir: {output_dir}

# Qualified invoice issuer registration number (T + 13 digits)
invoice_registration_number: {invoice_registration_number}

# --- Taxpayer Information ---
taxpayer:
  last_name: {last_name}
  first_name: {first_name}
  last_name_kana: {last_name_kana}
  first_name_kana: {first_name_kana}
  gender: {gender}
  date_of_birth: {date_of_birth}
  phone: {phone}
  my_number: {my_number}
  widow_status: {widow_status}
  disability_status: {disability_status}
  working_student: {working_student}
  relationship_to_head: {relationship_to_head}

# --- Address ---
address:
  postal_code: {postal_code}
  prefecture: {prefecture}
  city: {city}
  street: {street}
  building: {building}
  jan1_address: {jan1_address}

# --- Business Address (Only if different from home address) ---
business_address:
  postal_code:
  prefecture:
  city:
  street:
  building:

# --- Business Information ---
business:
  trade_name: {trade_name}
  industry_type: {industry_type}
  business_description: {business_description}
  establishment_year: {establishment_year}

# --- Filing Method ---
filing:
  submission_method: {submission_method}
  return_type: {return_type}
  blue_return_deduction: {blue_return_deduction}
  simple_bookkeeping: {simple_bookkeeping}
  electronic_bookkeeping: {electronic_bookkeeping}
  tax_office_name: {tax_office_name}

# --- Family Composition ---
family:
  has_spouse: {has_spouse}
  has_dependents: {has_dependents}
  dependent_count: {dependent_count}

# --- Housing Loan Deduction ---
housing_loan:
  applicable: {applicable}
  first_year: {first_year}

# --- Estimated Tax ---
estimated_tax:
  applicable: {applicable}
  amount: {amount}

# --- Document Directories (Optional) ---
invoices_dir: {invoices_dir}
withholding_slips_dir: {withholding_slips_dir}
past_returns_dir: {past_returns_dir}
deductions_dir: {deductions_dir}
receipts_dir: {receipts_dir}
bank_statements_dir: {bank_statements_dir}
credit_card_statements_dir: {credit_card_statements_dir}

Leave unconfigured items empty (only

key:

Handling of
my_number
: My Number is saved in the config YAML, but only

has_my_number: true/false

is returned in the output of

profile.py

. Do not output it in logs or conversations. It is only read directly from the config when inputting data into the final tax return preparation corner.

bash

shinkoku profile --config PATH

Step 6: Initialize Database

Confirm the
```
db_path
```
value; convert relative paths to absolute paths based on the CWD

Initialize the database using the

ledger.py init

command:

bash

shinkoku ledger init --db-path DB --fiscal-year YEAR

```
--fiscal-year
```
:
```
tax_year
```
set in Step 2
```
--db-path
```
: Value converted to absolute path

Step 7: Guide to Next Steps

After setup is completed, provide the following guidance:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Setup Completed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

■ Generated Files:
  → shinkoku.config.yaml (configuration file)
  → {db_path} (database)

■ Next Steps:
  1. /assess — Determine if filing is required and return type
  2. /gather — Confirm and collect required documents
  3. /journal — Enter journal entries and manage bookkeeping
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Output Handover Document

After presenting the summary, output the following file using the Write tool. This allows the results to be carried over to the next step even if the session is interrupted or compacted.

Output Step-by-Step File

Output to

.shinkoku/progress/01-setup.md

in the following format:

---
step: 1
skill: setup
status: completed
completed_at: "{current date YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# Setup Results

## Configuration Details

- Target Tax Year: {tax_year}
- Database Path: {db_path}
- Output Directory: {output_dir}
- Invoice Registration Number: {invoice_registration_number}

## Taxpayer Information

- Full Name: {last_name} {first_name}
- Date of Birth: {date_of_birth}
- My Number: Registered/Not Registered
- Widow/Single Parent: {widow_status}
- Disability Status: {disability_status}
- Working Student: {working_student}
- Relationship to Head of Household: {relationship_to_head}

## Address

- Home Address: {postal_code} {prefecture}{city}{street}{building}
- Address as of January 1: {jan1_address} (Same as home address/Different address)
- Business Address: Configured/Same as home address

## Business Information

- Trade Name: {trade_name}
- Industry Type: {industry_type}
- Business Description: {business_description}

## Filing Method

- Submission Method: {submission_method}
- Return Type: {return_type}
- Blue Return Special Deduction: {blue_return_deduction} JPY
- Competent Tax Office: {tax_office_name}

## Important Matters Affecting Deductions and Filing

- Spouse: Yes (Approximate Income: ○0,000 JPY)/No
- Dependents: Yes (○ people, including ○ under 16)/No
- Housing Loan Deduction: Applicable (First Year/From Second Year)/Not Applicable
- Estimated Tax: Applicable (Total ○ JPY)/Not Applicable
- Head of Household: Self / ○○ (Name)

## Document Directories

- Invoices: {invoices_dir}
- Withholding Slips: {withholding_slips_dir}
- Receipts: {receipts_dir}
- Bank Statements: {bank_statements_dir}
- Credit Card Statements: {credit_card_statements_dir}
- Deduction-Related Documents: {deductions_dir}
- Past Returns: {past_returns_dir}

## DB Initialization

- Initialization Result: Success
- Chart of Accounts: Registered

## Next Steps

Use /assess to determine if filing is required and return type

Mark unconfigured items as "Not Configured".

Update Progress Summary

Create a new

.shinkoku/progress/progress-summary.md

YAML frontmatter: fiscal_year, last_updated (current date), current_step: setup
Table: Status of all steps (mark setup as completed, others as pending)
Guidance to next steps

Guidance After Output

After outputting the file, inform the user:

"Handover document saved to
```
.shinkoku/progress/
```
. Results can be carried over to the next skill even if the session is interrupted."
Guidance to next steps

setup

NPX Install

Tags

SKILL.md Content (Chinese)