Yukiguni Agent Stack
Architecture · PRD · Agent spec cards · v0.1

Yukiguni Agent Stack

A multi-agent operating system for a lean ski-resort real estate developer in Japan. One CEO agent runs the deal pipeline; ten specialist agents do the sourcing, outreach, regulatory, diligence, underwriting, design, construction, capital and sales work; the founder and licensed professionals keep every decision that carries legal or financial weight.

Draft 2026-11-21 Markets Myoko · Hakuba · Nozawa · Niseko Agents 1 orchestrator + 10 workers Status For founder review
PART 1

System architecture

Hierarchical orchestrator–worker design. The CEO agent never does specialist work itself; it plans, dispatches, checks results against each agent's "done when" criteria, and escalates decisions to the founder. Workers never talk to each other directly. They read and write a shared Deal Record, which keeps every hand-off auditable.

1.1 Topology who talks to whom

flowchart TB
  F(["Founder (human)"])
  PRO(["Licensed professionals
行政書士 · 司法書士 · 一級建築士 · 宅建士 · 税理士 · 弁護士"]) CEO["A-00 CEO / Orchestrator"] F <-->|"goals · approvals · Daily Brief"| CEO subgraph ACQ["Acquire"] SRC["A-01 Sourcing"] OUT["A-02 Outreach"] end subgraph FEAS["Feasibility"] REG["A-03 Regulatory & Zoning"] DD["A-04 Title & Site DD"] UW["A-05 Market & Underwriting"] end subgraph BUILD["Design & Build"] ARC["A-06 Architect Assistant"] CON["A-07 Construction & Permits"] end subgraph MONEY["Capital & Exit"] CAP["A-08 Capital & IR"] SAL["A-09 Sales & Leasing"] end CEO --> ACQ & FEAS & BUILD & MONEY QA["A-10 Compliance Reviewer"] ACQ & FEAS & BUILD & MONEY -.->|"deliverables"| QA QA -.->|"pass / block"| CEO subgraph SHARED["Shared state"] DB[("Deal Records")] DOCS[("Document store")] KB[("Regulation KB")] AQ[["Approval queue"]] LOG[["Audit log + budget ledger"]] end ACQ & FEAS & BUILD & MONEY <--> SHARED AQ --> F PRO <-->|"sign-off, via founder"| F

Orchestration rules

  • Only the CEO dispatches work. Workers can request a sub-task by returning needs: [agent, question].
  • Every task carries a Task Brief (1.4) with a budget and an approval level.
  • The CEO accepts a deliverable only when its "done when" checks pass and, if in scope, the Compliance Reviewer passes it.
  • Rejected work goes back once with written reasons. A second failure escalates to the founder.

Shared state

  • Deal Record: one row per parcel or deal; single source of truth for stage, owner and next action.
  • Document store: registry copies, reports, models, drawings, versioned by deal ID.
  • Regulation KB: cached ordinances and maps per municipality, each with URL and retrieval date. Re-verified after 90 days.
  • Approval queue: every L2/L3 action waits here for the founder.
  • Audit log: every tool call, outbound draft, spend and decision.

Seasonal clock

  • Apr–May: owners decide to sell after the season; peak sourcing and outreach.
  • Apr–Nov: snow-free construction window; the critical path must finish enclosure before first heavy snow.
  • Dec–Mar: buyers and investors visit; peak sales, site tours and IR.
  • The CEO weights priorities by this calendar.

1.2 Deal pipeline & stage gates G0 → G9

Each deal moves through gates. A gate opens only when its exit criteria are met. The gate owner is who decides; agents prepare, humans decide at the red gates.

GateStageExit criteriaAgents workingDecided by
G0LeadLead Card with source URL, Buy Box fit scoreA-01CEO
G1ScreenedFit score ≥ 60, quick zoning check not "Not permitted", owner identified from 登記A-01, A-03 (quick), A-04 (registry pull)CEO, founder notified
G2ContactedApproved first-touch letter or broker inquiry sentA-02Founder approves each send
G3EngagedOwner or broker has replied with interest; call or meeting bookedA-02CEO
G4FeasibilityZoning Report + DD Report + Underwriting pack + 2 massing options, all reviewed by A-10; CEO Gate Memo with go / no-goA-03, A-04, A-05, A-06, A-10Founder
G5Offer / LOIMax bid approved; 買付証明書 or LOI signed by founder; 行政書士 / lawyer sign-off on zoning and titleA-05, A-08 (financing view)Founder + professionals
G6AcquiredSettlement done by 司法書士; foreign-exchange and land-use filings submittedA-03 (filings checklist), A-08Founder
G7DesignArchitect contracted; design accepted; permit set ready for 建築確認A-06, A-07, A-05 (re-underwrite)Founder + 一級建築士
G8BuildGC awarded; construction to completion inspection (完了検査)A-07, A-08 (lender draws)Founder
G9Sell / operateUnits sold via licensed 宅建士, or handed to operator with 旅館業 licenceA-09, A-08 (investor reporting)Founder

1.3 Approval levels what an agent may do on its own

LevelMeaningExamples
L0 AutonomousAgent acts, logs itWeb research, reading registries already paid for, running models, writing internal drafts, updating Deal Record fields it owns
L1 NotifyAgent acts, founder sees it in the Daily BriefAdvancing a deal G0→G1, spending within the task budget (e.g. ¥3,000 of registry pulls), re-prioritising the week
L2 Approve firstAgent prepares; founder approves in the queue; then the system executesAny message to an outside party (owner, broker, 役所, GC, investor), spend above budget, sharing documents externally
L3 Human onlyAgent may prepare material; a human performs the actOffers and price statements, signing anything, paying or moving money, permit submissions, legal opinions, contract awards, investor solicitation
Hard line. No agent signs, pays, makes an offer, files with a government office, or gives a legal opinion. In Japan those acts belong to licensed people (宅建士, 行政書士, 司法書士, 一級建築士, 弁護士) or to the founder. Agents cut their time per deal; they don't replace their stamp.

1.4 Data contracts the two objects everything passes through

// Task Brief: CEO → worker
{
  "task_id": "T-2026-1121-014",
  "deal_id": "D-MYK-0042",
  "agent": "A-03",
  "objective": "Can a 10-key lodge be built and
                licensed on this parcel?",
  "inputs": ["deal://D-MYK-0042/lead_card",
             "doc://D-MYK-0042/touki.pdf"],
  "constraints": ["cite every finding",
                  "JP sources first"],
  "budget": { "tokens": 400000, "jpy": 2000 },
  "approval_level": "L0",
  "due": "2026-11-24T18:00+09:00",
  "done_when": "card:A-03#done",
  "review": "A-10"
}
// Deal Record (abridged)
{
  "deal_id": "D-MYK-0042",
  "stage": "G3",
  "area": "Myoko / Akakura",
  "address": "新潟県妙高市赤倉 …",
  "chiban": ["…番", "…番"],
  "site_m2": 812,
  "asking_jpy": 68000000,
  "owner": { "ref": "crm://C-0193" },   // PII stays in CRM
  "fit_score": 78,
  "reports": { "zoning": "v2", "dd": "v1",
               "uw": "v3", "massing": null },
  "next_action": { "agent": "A-04",
                   "what": "boundary status",
                   "due": "2026-11-26" },
  "risks": ["土砂災害警戒区域 edge", "no 境界確定"],
  "log": "audit://D-MYK-0042"
}

Every worker returns a Result Envelope: {task_id, status: done | partial | blocked, deliverable_uri, done_when_checks: [{check, pass, evidence}], open_questions, needs, spend}. The CEO reads the checks, not just the prose.

1.5 Recommended tech stack

LayerChoiceWhy
Agent runtimeClaude Managed Agents (beta) with multi-agent enabled; CEO as lead, workers as sub-agents referenced by IDAnthropic hosts the loop and a sandbox per session, versioned agent configs, scheduled runs for the weekly sourcing sweep. Self-hosted alternative: Claude Agent SDK.
ModelsCEO, Regulatory, Underwriting, Compliance: claude-opus-5-5. Other workers: claude-sonnet-5-5. Bulk listing extraction: claude-haiku-5-5Judgment-heavy roles get the strongest model; high-volume reading uses the cheaper ones. Measure before downgrading any role.
Deal Records / CRMNotion or Airtable database (start), Postgres laterFounder can read and edit directly; agents use it through MCP.
DocumentsGoogle Drive, one folder per deal IDShared with professionals; versioned.
MessagingGmail (draft-only scope for agents), Slack or LINE for the Daily BriefAgents can draft but never send; send happens on approval.
Japan data sources国交省 不動産情報ライブラリ API, 登記情報提供サービス, 地理院地図, 重ねるハザードマップ, J-SHIS, municipal 例規集 and 都市計画 maps, BIT 競売, 空き家バンクPrimary public sources, citable in reports.
ObservabilityAudit log + per-deal spend ledger; Console session viewerFounder can see what each agent did and what it cost.
PART 2

Product requirements

Problem: a ski-resort developer needs the output of a 6–10 person team (acquisitions, analyst, permitting coordinator, project manager, IR, bilingual assistant) before revenue can support one. Most of that work is research, Japanese paperwork, modelling and drafting, which agents can do; the rest is judgment and licensed acts, which stay human.

2.1 Users

Founder (primary). Sets goals, approves L2/L3, reads one Daily Brief. Wants fewer hours per deal and faster no-gos.
Bilingual associate (optional, part-time). Clears the approval queue on outreach, handles calls and site visits.
Licensed professionals (external). Receive agent-prepared packs; sign off. Want clean, cited inputs.

2.2 Goals & success metrics targets to validate in Phase 1

GoalMetricBaseline (manual)Target
See more of the marketLeads screened per week~10150+
Faster no-gosLead → G4 feasibility pack3–4 weeks≤ 5 business days
Founder time on decisions onlyFounder hours per deal reaching G425–40 h≤ 4 h
Trustworthy researchRegulatory findings with a primary-source citationn/a100%
Trustworthy researchFindings overturned by 行政書士 / architect reviewn/a< 5%
Owner engagementReply rate on first-touch lettersunknown≥ 8%
Cost controlModel + data spend per G4 packn/a≤ ¥20,000
SafetyUnapproved external sends or spendsn/a0

2.3 Non-goals

  • Replacing licensed professionals or producing permit-ready drawings or legal opinions.
  • Autonomous negotiation, offers, payments or signatures.
  • Public-facing chat with buyers without a human in the loop.
  • Property management and hotel operations (later phase, separate spec).

2.4 Functional requirements

IDRequirementPriority
FR-01Founder can give goals in plain English or Japanese; the CEO turns them into Task Briefs and confirms its plan back in one message.P0
FR-02Daily Brief by 08:00 JST: decisions needed (with recommendation), pipeline moves, blockers, spend vs budget.P0
FR-03Weekly scheduled sourcing sweep across all sources for every target area, deduplicated against existing Deal Records.P0
FR-04Every regulatory and DD finding carries a source (URL or document + page/article) and retrieval date, or is marked "Unverified".P0
FR-05Approval queue: each item shows what will happen, to whom, the full text (JP + EN), cost, and Approve / Edit / Reject.P0
FR-06G4 Gate Memo bundles zoning, DD, underwriting and massing into one go / no-go page with links.P0
FR-07All owner-facing text is written in natural business Japanese (敬語) with an English translation for the founder.P0
FR-08Underwriting model is a real spreadsheet the founder can open and change, not numbers in prose.P1
FR-09Massing options rendered as diagrams with area tables; optional 3D site model.P1
FR-10Permit and construction tracker with critical path against the winter shutdown.P2
FR-11Investor materials trace every figure to an underwriting version ID.P2
FR-12Sales kit in EN / JP / 繁體中文, released only after 建築確認 is issued.P3

2.5 Non-functional requirements

Auditability
Every tool call, draft, spend and decision logged against a deal ID; replayable.
Privacy (個人情報保護法)
Owner names and addresses from registries live only in the CRM, used only for this acquisition purpose, never in prompts to outside services beyond what the task needs.
Cost guardrails
Per-task token and ¥ budgets; per-deal monthly cap; CEO halts and asks when 80% is reached.
Freshness
Regulation KB entries older than 90 days are re-verified before use in a G4 pack.
Bilingual
Japanese sources are read in Japanese; reports are in English with original JP terms kept beside the translation.
Security
Agents get draft-only email scopes and read-only finance access; secrets in a vault, never in prompts.

2.6 Rollout

PhaseWeeksAgents switched onExit test
P1 Desk research1–6A-00, A-01, A-03, A-04, A-05, A-103 real parcels taken to a G4 pack; 行政書士 overturns < 5% of zoning findings; founder ≤ 4 h each
P2 Contact & capital7–12+ A-02, A-0850 approved letters sent; zero unapproved sends; investor teaser for one deal
P3 Design & build13–24+ A-06, A-07Architect accepts agent-prepared brief; permit tracker live on an acquired site
P4 Exit25++ A-09Sales kit approved by 宅建士 partner; leads triaged within 24 h
Start Phase 1 in shadow mode: run agents on two parcels you have already analysed by hand and compare their reports with yours before trusting them on new ones.

2.7 Risks & mitigations

RiskMitigation
Wrong zoning conclusion leads to a bad acquisitionCitation required per row; A-10 review; 行政書士 sign-off is a G5 exit criterion; 事前相談 with the town office before offer.
Outreach perceived as spam or intrusivePostal letter or broker first; no marketing email without consent (特定電子メール法); founder approves every send; max 3 touches.
Agent drifts into licensed activity (brokerage, legal advice)Hard rules in each card; no agent acts as intermediary for third parties; licensed partner handles contracts and 重要事項説明.
Advertising pre-construction units too earlyA-09 blocked until 建築確認 is issued (宅建業法 advertising restriction).
Investor materials trigger securities rulesA-08 drafts only; counsel reviews any solicitation structure (金融商品取引法).
Stale data (ordinances, prices)KB freshness rule; every report shows retrieval dates.
Runaway costTask budgets, per-deal caps, weekly spend line in the Daily Brief.

2.8 Open questions for the founder

  • Buy Box: target areas, land size, price band, and build-to-sell vs build-to-hold mix?
  • Which entity buys (Japanese KK / GK vs foreign entity)? This changes 外為法 reporting and financing.
  • Which professionals are already retained, and who receives agent packs?
  • Deal Record home: Notion, Airtable or something you already use?
  • Monthly budget ceiling for model + data spend?
PART 3

Agent spec cards

Every card has the same six required fields: role, objective, inputs, tools, output format, and done when. Guardrails and hand-offs sit underneath. "Copy" puts the card on your clipboard as Markdown, ready to paste into an agent's system prompt.

IDAgentModelDefault levelPhase