setup

Setup Wizard

A skill to interactively perform the initial setup of shinkoku. It generates the configuration file (shinkoku.config.yaml) and initializes the database.

Step 0: Check CLI installation

shinkoku Check whether the command is available.

shinkoku --version Run
If the command does not exist: uv tool install git+https://github.com/kazukinagata/shinkoku Run to install it
If the command exists: uv tool upgrade shinkoku Run to update to the latest version

Step 1: Check existing configuration

CWD の shinkoku.config.yaml Read with the Read tool.

If the file exists: Display its contents and confirm whether to update. If not updating, exit the skill.
If the file does not exist: Start the setup wizard.

Step 2: Interview for basic settings

Confirm the following items with AskUserQuestion:

2-1. Target year

tax_year: Target year for the tax return (default: 2025)

2-1b. Presence of business income

has_business_income: Whether there is business income (including side business) (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)
2.8 Questions about the type of return (blue/white) and bookkeeping method (unnecessary if only salary income)

2-2. Registration number of a qualified invoice issuing business operator (only if there is business income)

invoice_registration_number: T + 13-digit number (optional, can be skipped)

Step 2.5: Interview for taxpayer information

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

2.5-1. Name

taxpayer.last_name: Last name
taxpayer.first_name: First name
taxpayer.last_name_kana: Last name (katakana)
taxpayer.first_name_kana: First name (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: My Number 12 digits (handle with care — store in config, but never display it in tool output or logs)

2.5-4. Status related to personal deductions (optional)

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

Step 2.6: Interview for address information

2.6-1. Home address

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

2.6-2. Address as of January 1 (only if different)

address.jan1_address: Address as of 1/1 (used to determine the municipality taxing resident tax)

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

business_address.postal_code 〜 business_address.building

Step 2.7: Hearing about business information

Confirm if there is business income.

business.trade_name: Trade name
business.industry_type: Industry
business.business_description: Business description
business.establishment_year: Year of opening

Step 2.8: Confirmation of filing method

Confirm the following items in order, and the blue return special deduction amount will beautomatically determineddo.

Hearing items

filing.submission_method: Submission method (e-tax / mail / in-person)
- If mail / in-person is selected, immediately after selection tell the following:
  
  The bookkeeping management and tax calculation functions of this plugin can be used, but automatic input to the tax return preparation corner (/e-tax skill) is exclusively for e-Tax submission and cannot be used. Input to the preparation corner must be done by yourself.
- If e-tax is selected, no notification required (full support)
filing.return_type: Type of filing (blue / white) — Ask only if there is business income(skip if there is no business income)
- If white is selected, immediately after selection tell the following:
  
  White return is supported. In the financial statements corner, a statement of income and expenses is used. Note that the bookkeeping function is designed based on double-entry bookkeeping, so bookkeeping will be performed at a level exceeding that required for white returns.
- If blue is selected, no notification required
filing.tax_office_name: Name of the tax office with jurisdiction

Automatic determination flow for the blue return special deduction

return_type が blue In the case of, determine the deduction amount by the following flow:

Ask about the bookkeeping method (double-entry bookkeeping / simple bookkeeping)
In the case of simple bookkeeping → simple_bookkeeping: true, deduction amount = 100,000 yen confirmed
In the case of double-entry bookkeeping:
- e-Tax submission (submission_method: e-tax) → deduction amount = 650,000 yen confirmed (electronic_bookkeeping is not required)
- Paper submission (submission_method: mail or in-person) → electronic_bookkeeping ask
  - true(with excellent electronic book storage) → deduction amount = 650,000 yen
    - If true is selected, immediately after selection tell the following:
      
      To apply excellent electronic book storage, it is necessary to submit in advance a "Notification Form Concerning Storage of National Tax-Related Books, etc. by Electromagnetic Records, etc." to the tax office with jurisdiction. The form of the notification can be downloaded from the National Tax Agency website. If applying from the Reiwa 9 tax year, submit the notification within Reiwa 8. In addition, confirmation of whether it has been submitted and diagnosis of the system's requirement satisfaction status can be performed with the /e-bookkeeping-compliance skill.
  - false → deduction amount = 550,000 yen
Display the determination result to the user and confirm

Related fields

filing.blue_return_deduction: Blue return special deduction amount (automatically determined; manual specification also possible)
- 650,000: Double-entry bookkeeping + (e-Tax filing or electronic bookkeeping storage) + filing by deadline
- 550,000: Double-entry bookkeeping + paper filing + filing by deadline (no e-Tax/electronic bookkeeping storage)
- 100,000: Simple bookkeeping or filing after deadline
filing.simple_bookkeeping: Whether simple bookkeeping (true / false, default: false)
filing.electronic_bookkeeping: Whether high-quality electronic bookkeeping storage is in place (true / false). Not required in the case of e-Tax filing (e-Tax alone is sufficient for the 650,000 yen deduction)

Step 2.9: Confirmation of important matters affecting deductions and filing (cannot be skipped)

The following items greatly affect income tax and resident tax, sobe sure to confirm all items. Obtain explicit answers for all items, including "not applicable." Do not proceed to the next step without confirming them.

2.9-1. Family structure (spouse and dependent relatives)

Confirm the following and save it in config. Details (income amount, disability classification, etc.) are registered in /income-tax .

family.has_spouse: Whether there is a spouse (true / false)
- If true:
  - Confirm the spouse's annual income (approximate) and determine the applicability of the spouse deduction/special deduction
  - Income of 480,000 yen or less → spouse deduction; 480,000 to 1,330,000 yen → special spouse deduction
  - Whether they are a business dedicated worker: A spouse receiving a salary as a blue-return business dedicated worker is not eligible for the spouse deduction
family.has_dependents: Whether there are dependent relatives (true / false)
- If true: confirm the number of people and an overview (children, parents, etc.)
- Include children under 16: Although not eligible for the dependent deduction, it is necessary for the resident tax non-taxation determination and per-capita levy determination, so it must be entered in "Matters concerning resident tax" in Part 2 of the tax return
- Exclude business dedicated workers: Blue-return business dedicated workers and white-return business dedicated workers do not qualify as dependent relatives
family.dependent_count: Number of dependent relatives (including those under 16)

* The My Number of the spouse and dependent relatives is collected in Step 1.5 of the /income-tax skill.

2.9-2. Housing loan deduction

housing_loan.applicable: Whether the housing loan deduction applies (true / false)
- If true:
  - housing_loan.first_year: Whether it is the first year (true / false)
  - First year → /income-tax Prepare the calculation statement in Step 3.7 (separate attached documents are required)
  - Second year onward → If it has already been applied through year-end adjustment, additional procedures in the final tax return are generally unnecessary

2.9-3. Prepayment of tax

estimated_tax.applicable: Whether there is prepayment of tax (true / false)
- Judgment criterion: If column ㊺ (tax amount to be paid) on the previous year's final tax return is 150,000 yen or more → prepayment of tax applies
- If true:
  - estimated_tax.amount: Confirm the total amount of prepaid tax (1st installment + 2nd installment, int yen)
  - If a reduction application has been filed, enter the amount after reduction

2.9-4. Name of the head of household (if not the person themselves)

In step 2.5-2, relationship_to_head is other than "the person themselves":

taxpayer.household_head_name: Confirm the name of the head of household (must be stated on the return)

Step 3: Path settings

Confirm the following paths. Present the default values, and if there are no changes, adopt them as is.

db_path: Path of the database file (default: ./shinkoku.db）
output_dir: Output destination directory for progress files, etc. (default: ./output）

Step 4: Document directory settings (optional)

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

invoices_dir: Directory for invoice PDFs, etc.
withholding_slips_dir: Directory for withholding tax slips
receipts_dir: Directory for receipts and invoices
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 tax return data

Step 5: Preview and save settings

Preview the collected settings in YAML format
Obtain the user's confirmation
With the Write tool, to the CWD shinkoku.config.yaml Save

The YAML format follows the template below:

# shinkoku ユーザー設定ファイル
# /setup スキルで対話的に生成できます。

# 対象年度
tax_year: {tax_year}

# 事業所得の有無（副業含む）
has_business_income: {has_business_income}

# データベースファイルのパス
db_path: {db_path}

# 進捗ファイル等の出力先ディレクトリ
output_dir: {output_dir}

# 適格請求書発行事業者の登録番号（T + 13桁）
invoice_registration_number: {invoice_registration_number}

# --- 納税者情報 ---
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:
  postal_code: {postal_code}
  prefecture: {prefecture}
  city: {city}
  street: {street}
  building: {building}
  jan1_address: {jan1_address}

# --- 事業所住所（自宅と異なる場合のみ） ---
business_address:
  postal_code:
  prefecture:
  city:
  street:
  building:

# --- 事業情報 ---
business:
  trade_name: {trade_name}
  industry_type: {industry_type}
  business_description: {business_description}
  establishment_year: {establishment_year}

# --- 申告方法 ---
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:
  has_spouse: {has_spouse}
  has_dependents: {has_dependents}
  dependent_count: {dependent_count}

# --- 住宅ローン控除 ---
housing_loan:
  applicable: {applicable}
  first_year: {first_year}

# --- 予定納税 ---
estimated_tax:
  applicable: {applicable}
  amount: {amount}

# --- 書類ディレクトリ（任意） ---
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 the values of unset items empty (key: only).

my_number Handling of: The My Number is saved in the config YAML, butprofile.py in the output of has_my_number: true/false only return. Do not output to logs or conversations. Read directly from the config only when entering into the tax return preparation corner.

shinkoku profile --config PATH

Step 5.5: Git safety settings

To prevent the user's personal information and financial data from being accidentally committed to git,.gitignore set.

Procedure

git rev-parse --is-inside-work-tree and check whether the CWD is a git repository
If it is not a git repository → Display the following message and skip:

The current directory is not a git repository. If you make it a git repository in the future,.gitignore add shinkoku-related files to prevent leakage of personal information.
If it is a git repository: a. CWD の .gitignore with the Read tool (if it does not exist, proceed on the assumption that it will be newly created) b. Check whether the following required entries are included in .gitignore :
```
# shinkoku 確定申告データ（個人情報を含む — 削除しないこと）
shinkoku.config.yaml
shinkoku.db
shinkoku.db-wal
shinkoku.db-shm
.shinkoku/
output/
```
c. If there are document directories set in Step 4 (invoices_dir, receipts_dir , etc.), add them as well d. If there are missing entries:
- Present the list of entries to be added to the user
- After obtaining the user's confirmation, .gitignore append to (preserve existing content and add at the end) e. If all entries are already included → ".gitignore is already configured" and skip

Step 6: Initialize the database

db_path Check the value of , and if it is a relative path, convert it to an absolute path based on the CWD
ledger.py init Initialize the database with the command:
```
shinkoku ledger init --db-path DB --fiscal-year YEAR
```
- --fiscal-year: The set in Step 2 tax_year
- --db-path: The value converted to an absolute path

Step 7: Guidance for the next step

After setup is complete, provide the following guidance:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
セットアップ完了
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

■ 生成されたファイル:
  → shinkoku.config.yaml（設定ファイル）
  → {db_path}（データベース）

■ 次のステップ:
  1. /assess — 申告要否・種類の判定
  2. /gather — 必要書類の確認・収集
  3. /journal — 仕訳入力・帳簿管理
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Output of the handover document

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

Output of per-step files

.shinkoku/progress/01-setup.md Output to in the following format:

---
step: 1
skill: setup
status: completed
completed_at: "{当日日付 YYYY-MM-DD}"
fiscal_year: {tax_year}
---

# セットアップ結果

## 設定内容

- 対象年度: {tax_year}
- データベースパス: {db_path}
- 出力ディレクトリ: {output_dir}
- インボイス登録番号: {invoice_registration_number}

## 納税者情報

- 氏名: {last_name} {first_name}
- 生年月日: {date_of_birth}
- マイナンバー: {登録済み/未登録}
- 寡婦/ひとり親: {widow_status}
- 障害者区分: {disability_status}
- 勤労学生: {working_student}
- 世帯主との続柄: {relationship_to_head}

## 住所

- 自宅: {postal_code} {prefecture}{city}{street}{building}
- 1/1時点の住所: {jan1_address}（同上/異なる住所）
- 事業所住所: {設定あり/自宅と同じ}

## 事業情報

- 屋号: {trade_name}
- 業種: {industry_type}
- 事業内容: {business_description}

## 申告方法

- 提出方法: {submission_method}
- 申告の種類: {return_type}
- 青色申告特別控除: {blue_return_deduction}円
- 所轄税務署: {tax_office_name}

## 控除・申告に影響する重要事項

- 配偶者: {あり（概算所得: ○万円）/ なし}
- 扶養親族: {あり（○人、うち16歳未満○人）/ なし}
- 住宅ローン控除: {適用あり（初年度/2年目以降）/ 適用なし}
- 予定納税: {あり（合計○円）/ なし}
- 世帯主: {本人 / ○○（氏名）}

## 書類ディレクトリ

- 請求書: {invoices_dir}
- 源泉徴収票: {withholding_slips_dir}
- レシート: {receipts_dir}
- 銀行明細: {bank_statements_dir}
- クレカ明細: {credit_card_statements_dir}
- 控除関連: {deductions_dir}
- 過去の申告: {past_returns_dir}

## DB初期化

- 初期化結果: 成功
- 勘定科目マスタ: 登録済み

## 次のステップ

/assess で申告要否・種類を判定する

For items that are not set, write "Not set".

Update of the progress summary

.shinkoku/progress/progress-summary.md Create as new:

YAML frontmatter: fiscal_year, last_updated (current date), current_step: setup
Table: Describe the status of all steps (set setup to completed, and the others to pending)
Describe the guidance for the next step

Guidance after output

After outputting the file, tell the user the following:

"I saved the handover document to .shinkoku/progress/ . Even if the session is interrupted, you can carry over the results in the next skill."
Guidance for the next step