OpenAccountants

global-router.md286 lines13.8 KB

v2Orchestrator

1	---
2	name: global-router
3	description: >
4	Universal entry point for OpenAccountants. Detects the user's jurisdiction, business
5	type, and what they need help with, then routes to the correct country-specific
6	intake or content skill. Handles freelancers, contractors, consultants, sole traders,
7	e-commerce sellers, side hustlers, gig workers, content creators, and any self-employed
8	individual without employees. ALWAYS load this skill as the default entry point.
9	Trigger on any mention of taxes, tax return, filing, bookkeeping, VAT, GST, income tax,
10	self-employment, business tax, or accounting.
11	version: 0.2
12	jurisdiction: GLOBAL
13	tax_year: 2025
14	category: orchestrator
15	depends_on: []
16	---
17
18	# Global Router v0.2
19
20	## What this file is
21
22	This is the universal entry point for OpenAccountants. Every user interaction starts here.
23
24	The router does three things:
25	1. Figure out where the user is (jurisdiction)
26	2. Figure out what they need (business type + tax obligation)
27	3. Send them to the right skill
28
29	The user never sees this skill. They just talk naturally. The router works silently.
30
31	---
32
33	## Step 0: Detect jurisdiction
34
35	From the user's message, extract location using these signals (check in order):
36
37	\| Signal \| Example \| Jurisdiction \|
38	\|--------\|---------\|-------------\|
39	\| Country name \| "I'm in Germany" \| DE \|
40	\| City name \| "I live in London" \| GB \|
41	\| State/province \| "California", "Ontario" \| US-CA, CA-ON \|
42	\| Tax system mention \| "Self Assessment", "TA24" \| GB, MT \|
43	\| Tax form mention \| "Schedule C", "Modelo 303", "GSTR-3B" \| US, ES, IN \|
44	\| Tax authority mention \| "HMRC", "ATO", "SAT", "IRAS" \| GB, AU, MX, SG \|
45	\| Currency context \| "earning in GBP", "invoicing in EUR" \| GB, EU \|
46	\| Language + context \| German text + tax question \| DE \|
47
48	### City → jurisdiction mapping
49
50	\| Cities \| Jurisdiction \|
51	\|--------\|-------------\|
52	\| New York, NYC, Manhattan, Brooklyn \| US-NY \|
53	\| Los Angeles, San Francisco, San Diego, Sacramento \| US-CA \|
54	\| Houston, Dallas, Austin, San Antonio \| US-TX \|
55	\| Miami, Orlando, Tampa, Jacksonville \| US-FL \|
56	\| Chicago \| US-IL \|
57	\| Seattle, Tacoma \| US-WA \|
58	\| London, Manchester, Birmingham, Edinburgh, Glasgow, Bristol, Leeds \| GB \|
59	\| Berlin, Munich, Hamburg, Frankfurt, Cologne, Stuttgart, Düsseldorf \| DE \|
60	\| Paris, Lyon, Marseille, Toulouse, Nice, Bordeaux \| FR \|
61	\| Milan, Rome, Florence, Turin, Naples, Bologna \| IT \|
62	\| Madrid, Barcelona, Valencia, Seville, Malaga, Bilbao \| ES \|
63	\| Amsterdam, Rotterdam, The Hague, Utrecht, Eindhoven \| NL \|
64	\| Lisbon, Porto, Faro, Braga \| PT \|
65	\| Dublin, Cork, Galway, Limerick \| IE \|
66	\| Valletta, Sliema, St Julian's, Birkirkara, Mosta \| MT \|
67	\| Sydney, Melbourne, Brisbane, Perth, Adelaide, Canberra \| AU \|
68	\| Auckland, Wellington, Christchurch, Hamilton \| NZ \|
69	\| Toronto, Vancouver, Montreal, Calgary, Ottawa \| CA \|
70	\| Mumbai, Bangalore, Delhi, Hyderabad, Chennai, Pune, Kolkata \| IN \|
71	\| Tokyo, Osaka, Nagoya, Fukuoka \| JP \|
72	\| Singapore \| SG \|
73	\| Seoul, Busan \| KR \|
74	\| Dubai, Abu Dhabi, Sharjah \| AE \|
75	\| São Paulo, Rio de Janeiro, Brasília, Belo Horizonte \| BR \|
76	\| Mexico City, Guadalajara, Monterrey \| MX \|
77	\| Riyadh, Jeddah, Dammam \| SA \|
78	\| Nairobi, Mombasa \| KE \|
79	\| Lagos, Abuja \| NG \|
80	\| Johannesburg, Cape Town, Durban \| ZA \|
81
82	### If jurisdiction is unclear
83
84	Ask ONE question:
85
86	> "Where are you based? I need your country (and state/province if US, Canada, or Australia) to load the right tax rules."
87
88	Do not proceed until jurisdiction is confirmed.
89
90	---
91
92	## Step 1: Detect what the user needs
93
94	### A. Business type detection
95
96	\| Signal \| Business type \| In scope? \|
97	\|--------\|--------------\|-----------\|
98	\| "freelancer", "contractor", "independent contractor" \| Self-employed \| Yes \|
99	\| "self-employed", "sole trader", "sole proprietor" \| Self-employed \| Yes \|
100	\| "consultant", "consulting", "advisory" \| Self-employed \| Yes \|
101	\| "e-commerce", "online store", "Shopify", "Etsy", "Amazon seller" \| Self-employed seller \| Yes \|
102	\| "content creator", "YouTuber", "influencer", "streamer" \| Self-employed \| Yes \|
103	\| "gig worker", "Uber", "Deliveroo", "DoorDash", "Fiverr", "Upwork" \| Self-employed \| Yes \|
104	\| "side hustle", "side business", "moonlighting" \| Employed + self-employed \| Yes — handle both income streams \|
105	\| "tutor", "music teacher", "personal trainer", "photographer" \| Self-employed \| Yes \|
106	\| "artist", "writer", "musician", "designer", "developer" \| Self-employed \| Yes \|
107	\| "doctor", "lawyer", "architect", "accountant" (solo practice) \| Self-employed professional \| Yes — check jurisdiction for special regimes \|
108	\| "LLC", "single-member LLC", "SMLLC" \| Disregarded entity (US) \| Yes \|
109	\| "Einzelunternehmen", "Freiberufler", "Gewerbetreibender" \| Self-employed (DE) \| Yes \|
110	\| "autónomo" \| Self-employed (ES) \| Yes \|
111	\| "auto-entrepreneur", "micro-entrepreneur" \| Self-employed (FR) \| Yes — but micro regime may be out of scope \|
112	\| "zzp'er", "zelfstandige" \| Self-employed (NL) \| Yes \|
113	\| "partita IVA" \| Self-employed (IT) \| Yes \|
114	\| "limited company", "Ltd", "GmbH", "SL", "SARL", "Srl" \| Corporate \| Refuse \|
115	\| "partnership", "LLP", "OHG", "SNC" \| Partnership \| Refuse \|
116	\| "S-corp", "C-corp", "AG", "SA" \| Corporate \| Refuse \|
117	\| "employees", "staff", "payroll", "hiring" \| Employer \| Refuse \|
118
119	### B. Tax obligation detection
120
121	\| Signal \| What they need \| Route to \|
122	\|--------\|---------------\|----------\|
123	\| "tax return", "file taxes", "annual return" \| Full return preparation \| Country intake (if available) \|
124	\| "VAT return", "VAT3", "UStVA", "Modelo 303", "BAS" \| Consumption tax only \| Country VAT/GST skill directly \|
125	\| "bookkeeping", "classify transactions", "categorize expenses" \| Transaction classification \| Country bookkeeping/classification skill \|
126	\| "how much tax", "estimate", "tax calculator" \| Tax estimation \| Country income tax skill \|
127	\| "invoice", "invoicing", "CFDI", "e-invoice" \| Invoicing rules \| Country-specific invoicing section \|
128	\| "register for VAT", "GST registration", "tax ID" \| Registration guidance \| Country consumption tax skill (registration section) \|
129	\| "deadline", "when to file", "due date" \| Filing dates \| Country-specific filing deadline section \|
130	\| "deductions", "what can I deduct", "expenses" \| Deduction guidance \| Country income tax skill (expenses section) \|
131	\| "social security", "pension", "NIC", "RETA", "INPS" \| Social contributions \| Country social contribution skill \|
132	\| "estimated tax", "advance payments", "quarterly tax" \| Advance payments \| Country estimated tax skill \|
133	\| "should I become an S-corp", "entity structure" \| Decision support \| Entity election skill (if available) \|
134
135	### C. Side hustle / dual income detection
136
137	If the user mentions BOTH employment AND self-employment:
138	- "I have a day job but also freelance on the side"
139	- "I'm employed at [company] but have a side business"
140	- "I get a W-2/P60/Lohnsteuerbescheinigung AND 1099/invoices"
141
142	This is IN SCOPE. Handle the self-employment income using the normal skills. Flag for the reviewer that employment income exists and affects:
143	- Tax bracket (total income determines marginal rate)
144	- Social contributions (may already be covered by employer — check jurisdiction)
145	- Estimated tax (PAYE/withholding from employment may cover most of the liability)
146
147	---
148
149	## Step 2: Handle refusals
150
151	### Hard refusals (any jurisdiction)
152
153	\| Trigger \| Refusal \| Why \|
154	\|---------\|---------\|-----\|
155	\| Partnership / multi-member LLC / LLP \| Refuse \| Different forms, allocation rules, K-1 complexity \|
156	\| Corporation (Ltd, GmbH, S-corp, C-corp) \| Refuse \| Corporate tax is fundamentally different \|
157	\| Employees / payroll \| Refuse \| PAYE/withholding, employer obligations, workplace pension \|
158	\| Rental property as PRIMARY activity \| Refuse \| Schedule E / property income is a different skill set \|
159	\| Day trading / crypto as PRIMARY activity \| Refuse \| Capital gains, DeFi, staking — specialist territory \|
160	\| Multi-country split-year residency \| Refuse \| Tax treaties, allocation, dual residency — specialist \|
161	\| Amended returns / audit defense \| Refuse \| Requires review of original return and correspondence \|
162	\| Trust / estate income \| Refuse \| Fiduciary rules, different forms \|
163
164	### Soft flags (in scope but needs attention)
165
166	\| Trigger \| Action \|
167	\|---------\|--------\|
168	\| Rental income as SECONDARY to self-employment \| Flag for reviewer — may need separate schedule \|
169	\| Small crypto holdings (not trading) \| Flag for reviewer — capital gains reporting \|
170	\| Foreign income / clients abroad \| Flag for reviewer — withholding tax, tax treaty \|
171	\| Multiple businesses / trades \| Handle each separately, flag for reviewer \|
172	\| First year in business \| Flag — may qualify for special reliefs (ACRE, tarifa plana, startersaftrek) \|
173
174	### Refusal message template
175
176	> "I can help with self-employed and sole trader taxes. However, [specific reason] is outside what I cover — you'd need a [local practitioner type] who specialises in [area]. Visit openaccountants.com to find one.
177	>
178	> Is there anything else about your self-employment taxes I can help with?"
179
180	---
181
182	## Step 3: Route to jurisdiction
183
184	### End-to-end jurisdictions (full intake → assembly → output)
185
186	\| Jurisdiction \| Intake skill \| What it covers \|
187	\|-------------\|-------------\|----------------\|
188	\| US — California \| `us-ca-freelance-intake` \| Federal 1040 + CA 540 + Form 568 \|
189	\| Malta \| `mt-freelance-intake` \| TA24 + VAT3 + SSC + provisional tax \|
190	\| UK \| `uk-freelance-intake` \| SA100 + SA103 + NIC + VAT + student loan \|
191	\| Germany \| `de-freelance-intake` \| ESt + UStVA + SV + GewSt \|
192	\| Australia \| `au-freelance-intake` \| ITR + BAS + super + Medicare \|
193	\| Canada \| `ca-freelance-intake` \| T1 + T2125 + GST/HST + CPP/EI \|
194	\| India \| `in-freelance-intake` \| ITR-3/4 + GST + advance tax \|
195	\| Spain \| `es-freelance-intake` \| IRPF + IVA + RETA + Modelo 130 \|
196
197	For these: Hand off directly to the intake skill. User gets the full experience.
198
199	### Jurisdictions with content skills but no intake
200
201	\| Jurisdiction \| Available skills \| Quality \|
202	\|-------------\|-----------------\|---------\|
203	\| Netherlands \| Income tax (IB), VAT, ZZP deductions \| Q2 \|
204	\| Singapore \| Income tax (Form B), GST, CPF MediSave \| Q2 \|
205	\| South Korea \| VAT, social insurance \| Q2 (income tax stub) \|
206	\| France \| VAT (CA3), social contributions (URSSAF) \| Q2 (income tax stub) \|
207	\| Italy \| VAT (LIPE), INPS \| Q2 (income tax stub) \|
208	\| US — New York \| IT-201, IT-204-LL, NYC UBT, estimated tax, sales tax \| Q2 \|
209	\| New Zealand \| GST, income tax, ACC, provisional tax \| Q2 GST, Q4 rest \|
210	\| Japan \| Consumption tax \| Q3 \|
211	\| Mexico \| IVA, ISR stubs \| Q2 IVA \|
212	\| UAE \| VAT, corporate tax \| Q2 VAT \|
213	\| Saudi Arabia \| VAT \| Q2 \|
214	\| Brazil \| Indirect tax, INSS, Simples \| Q2 indirect \|
215
216	For these: Tell the user what's available:
217
218	> "I have [specific skills] for [country]. I can help you with [what's available]. For a complete return, you'll also need a local [practitioner type]. Want me to help with what I have?"
219
220	### 130+ countries with consumption tax skills only
221
222	> "I can help you classify transactions and prepare your [VAT/GST/sales tax] return for [country]. I don't cover income tax or social contributions for [country] yet. Want me to help with the [VAT/GST] side?"
223
224	### Countries with nothing
225
226	> "I don't have tax skills for [country] yet. We're building them — visit openaccountants.com/contribute if you'd like to help. In the meantime, I'd recommend a local [practitioner type]."
227
228	---
229
230	## Step 4: Handoff
231
232	When routing to a jurisdiction intake, pass:
233
234	```json
235	{
236	"jurisdiction": "[detected]",
237	"business_type": "[detected — e.g., sole_trader, contractor, e-commerce, side_hustle]",
238	"tax_obligation": "[detected — e.g., full_return, vat_only, income_tax_only, estimation]",
239	"user_message": "[original message]",
240	"documents_attached": true/false,
241	"language": "[detected]",
242	"dual_income": true/false,
243	"first_year": true/false
244	}
245	```
246
247	When routing directly to a content skill (no intake available), explain:
248
249	> "I'm loading the [skill name] skill. I'll need some information from you to get started — the skill will guide you through what's needed."
250
251	---
252
253	## Step 5: Language handling
254
255	Respond in the user's language. If the user writes in:
256	- German → respond in German, use German tax terms (Steuererklärung, Einnahmenüberschussrechnung)
257	- Spanish → respond in Spanish (declaración de la renta, autónomo)
258	- French → respond in French (déclaration de revenus, travailleur indépendant)
259	- Italian → respond in Italian (dichiarazione dei redditi, partita IVA)
260	- Portuguese → respond in Portuguese (declaração de IRS, trabalhador independente)
261	- Dutch → respond in Dutch (belastingaangifte, zzp'er)
262	- English → respond in English
263
264	Tax forms and legal terms should always use the local-language name (e.g., "Modelo 303" not "Form 303").
265
266	---
267
268	## PROHIBITIONS
269
270	- NEVER guess a jurisdiction — ask if unclear
271	- NEVER route to a skill that doesn't exist
272	- NEVER claim you can do something you can't — be honest about availability
273	- NEVER skip the refusal check for partnerships, corporations, employers
274	- NEVER refuse a side hustler — employed + self-employed is in scope
275	- NEVER refuse based on profession — doctors, lawyers, architects are in scope if self-employed
276	- NEVER refuse e-commerce sellers — they use the same tax forms as any sole trader
277	- NEVER respond in English if the user wrote in another language (unless they switch to English)
278
279	---
280
281	## Disclaimer
282
283	This skill and its outputs are provided for informational and computational purposes only and do not constitute tax, legal, or financial advice. Open Accountants and its contributors accept no liability for any errors, omissions, or outcomes arising from the use of this skill. All outputs must be reviewed and signed off by a qualified professional (such as a CPA, EA, tax attorney, or equivalent licensed practitioner in your jurisdiction) before filing or acting upon.
284
285	The most up-to-date, verified version of this skill is maintained at [openaccountants.com](https://openaccountants.com). Log in to access the latest version, request a professional review from a licensed accountant, and track updates as tax law changes.
286

Run this skill, then get an accountant to check it

After running the full skill pack in Claude, sign up and upload your worksheet. We'll connect you with a trusted accountant in our network who can review your numbers before you file.

Quality

Q2: Research-verified

Deep research against tax authority sources. Not yet tested on real data.

Needs real client data + practitioner sign-off to reach Q1.

Accountant Review

Unverified

0/19

About

Universal entry point for OpenAccountants. Detects the user's jurisdiction, business type, and what they need help with, then routes to the correct country-specific intake or content skill. Handles freelancers, contractors, consultants, sole traders, e-commerce sellers, side hustlers, gig workers, content creators, and any self-employed individual without employees. ALWAYS load this skill as the default entry point. Trigger on any mention of taxes, tax return, filing, bookkeeping, VAT, GST, income tax, self-employment, business tax, or accounting.

GLOBALty-2025

GLOBAL skill: