Building Séance Kit with Kiro specs steering and MCP
This post accompanies the Kiroween 2026 hackathon entry in the Skeleton Crew category. Séance Kit is a reusable foundation for local-first agent applications, demonstrated by two working apps: Archive Séance for chat exports and Inbox Exorcist for email archives.
AI disclosure: This article was drafted by Codex from the project repository and recorded verification results. The project includes work with Kiro, Claude Code and Codex; their contributions are described below and in KIRO_USAGE.md.
Try the labelled demo Watch the working project Explore the MIT-licensed source
The useful part of the project is the shared foundation: typed tools, an agent loop, approvals, storage adapters and a reusable interface. The two applications test whether that foundation can support different data and workflows without moving app-specific logic into the core.
Turn requirements into observable behavior
The tracked requirements came before the scaffold. They make product decisions testable. A write or destructive tool must wait for approval. The Mock provider must show a persistent Demo mode badge. Both apps must work offline after their first load, except for real-model requests.
The design connects these requirements to contracts such as ToolRegistry, Provider and Storage. Tasks then link implementation work back to the requirement IDs. The files stay in .kiro/specs/seance-kit.
One concrete lesson came from reviewing the offline requirement again: it existed in the requirements, but the implementation and task coverage were missing. The follow-up added scoped service workers and offline browser tests. Each application caches its own build output and uses its own shell for offline navigation.
A requirement was useful because it could lead to an implementation check and a test, rather than merely a checked box.
Local-first does not mean a real model works without a network. Archives are stored in the browser; a real-provider call sends the requested context to the configured provider. Keys are stored in a reserved secrets collection and excluded from exports. The scripted demo needs no key and says that it is scripted.
Keep conventions beside the code
Five steering files cover the product, structure, technology, testing and design language. Their rules are specific enough to guide decisions: app tools and importers stay in their app folders; storage goes through one interface; deletion is recoverable; Inbox tools never send mail; shared controls use the same dark theme and focus treatment.
These conventions matter when the two apps differ. Parsing an email archive belongs in Inbox Exorcist. Resetting an agent run or deciding whether a write needs approval belongs in the shared foundation. Explicit boundaries help keep the starter reusable.
The repository also contains three hook definitions:
- a shared-package typecheck prompt
- a task-completion check prompt
- a session-start status command
The task prompt asks for lint, type checks and tests, task updates, and retained regression examples. A hook definition describes the intended workflow; it does not prove that every hook executed successfully. The write-up separates configuration screenshots, saved test output and directly observed tool calls.
Define tools once and exercise them through MCP
Each tool has a zod input schema and an explicit risk: read, write or destructive. The registry derives model and MCP definitions from the same tools. The risk also controls whether execution waits for a user decision.
Both application MCP servers were connected in Kiro, with seven tools each. An actual search_conversations call for “sourdough” and a search_emails call for “boiler” each returned the expected fictional sample record. An additional Archive check imported a sample Storage.exportAll export into isolated FileStorage and queried it from Kiro.
In that tested Kiro session, read calls still requested one-time permission despite the configured autoApprove list. No MCP write was exercised. Keeping those details in the Kiro usage record makes the demonstration more useful than a claim that the configuration simply worked automatically.
Demonstrate decisions and recovery
The video shows the applications doing work. Archive imports public samples, searches a chat and proposes a tag. Reject leaves the chat unchanged. Inbox shows the complete list of five messages before Banish; Allow changes the visible Inbox count from 18 to 13, and Undo restores it to 18.
A separate real-provider segment uses the owner's configured deepseek-flash model. It searches and reads a sample chat. A subsequent explicit request proposes a tag through the approval gate, and that change is rejected. This demonstrates the configured path; it does not certify every provider or endpoint.
The published video combines edited actual interaction captures with actual Kiro evidence. It uses synthetic English narration, discloses that narration, and includes English captions. All sample records are fictional.
Test the contracts that make the template reusable
The project uses Vitest, property tests, shared storage contract tests, Playwright and axe. The recorded regressions include duplicate conversation IDs during import and Markdown role markers inside message bodies. Retaining those examples helps test the behavior the product promises.
For the video-link publication update, local typecheck, lint, 342 unit/property tests, build and 57 browser tests passed. The hosted CI run and Cloudflare deployment also passed. Browser coverage includes offline paths, keyboard interaction, provider mode and accessibility checks. These checks support the tested paths; they are not a claim that every possible archive or model was tested.
Tool attribution and what comes next
The development record includes Kiro-attributed implementation and reviews, plus Claude Code and Codex contributions. Codex handled the November 17 follow-up, performance work, evidence capture, video production and publication closeout described in KIRO_USAGE.md.
This article does not attribute every line, test run or media asset to Kiro. The project uses Kiro IDE, specs, steering, hooks and MCP. It does not claim use of Kiro Crew or Powers.
After the submission, the next useful step is feedback from developers trying the starter for a different local-first agent app. The source, concrete history and evidence are available in KIRO_USAGE.md.
This post accompanies the Kiroween 2026 hackathon entry in the Skeleton Crew category. Séance Kit is a reusable foundation for local-first agent applications, demonstrated by two working apps: Archive Séance for chat exports and Inbox Exorcist for email archives.
AI disclosure: This article was drafted by Codex from the project repository and recorded verification results. The project includes work with Kiro, Claude Code and Codex; their contributions are described below and in KIRO_USAGE.md.
The useful part of the project is the shared foundation: typed tools, an agent loop, approvals, storage adapters and a reusable interface. The two applications test whether that foundation can support different data and workflows without moving app-specific logic into the core.
Turn requirements into observable behavior
The tracked requirements came before the scaffold. They make product decisions testable. A write or destructive tool must wait for approval. The Mock provider must show a persistent Demo mode badge. Both apps must work offline after their first load, except for real-model requests.
The design connects these requirements to contracts such as ToolRegistry, Provider and Storage. Tasks then link implementation work back to the requirement IDs. The files stay in .kiro/specs/seance-kit.
One concrete lesson came from reviewing the offline requirement again: it existed in the requirements, but the implementation and task coverage were missing. The follow-up added scoped service workers and offline browser tests. Each application caches its own build output and uses its own shell for offline navigation.
A requirement was useful because it could lead to an implementation check and a test, rather than merely a checked box.
Local-first does not mean a real model works without a network. Archives are stored in the browser; a real-provider call sends the requested context to the configured provider. Keys are stored in a reserved secrets collection and excluded from exports. The scripted demo needs no key and says that it is scripted.
Keep conventions beside the code
Five steering files cover the product, structure, technology, testing and design language. Their rules are specific enough to guide decisions: app tools and importers stay in their app folders; storage goes through one interface; deletion is recoverable; Inbox tools never send mail; shared controls use the same dark theme and focus treatment.
These conventions matter when the two apps differ. Parsing an email archive belongs in Inbox Exorcist. Resetting an agent run or deciding whether a write needs approval belongs in the shared foundation. Explicit boundaries help keep the starter reusable.
The repository also contains three hook definitions: a shared-package typecheck prompt, a task-completion check prompt, and a session-start status command.
The task prompt asks for lint, type checks and tests, task updates, and retained regression examples. A hook definition describes the intended workflow; it does not prove that every hook executed successfully. The write-up separates configuration screenshots, saved test output and directly observed tool calls.
Define tools once and exercise them through MCP
Each tool has a zod input schema and an explicit risk: read, write or destructive. The registry derives model and MCP definitions from the same tools. The risk also controls whether execution waits for a user decision.
Both application MCP servers were connected in Kiro, with seven tools each. An actual search_conversations call for “sourdough” and a search_emails call for “boiler” each returned the expected fictional sample record. An additional Archive check imported a sample Storage.exportAll export into isolated FileStorage and queried it from Kiro.
In that tested Kiro session, read calls still requested one-time permission despite the configured autoApprove list. No MCP write was exercised. Keeping those details in the Kiro usage record makes the demonstration more useful than a claim that the configuration simply worked automatically.
Demonstrate decisions and recovery
The video shows the applications doing work. Archive imports public samples, searches a chat and proposes a tag. Reject leaves the chat unchanged. Inbox shows the complete list of five messages before Banish; Allow changes the visible Inbox count from 18 to 13, and Undo restores it to 18.
A separate real-provider segment uses the owner's configured deepseek-flash model. It searches and reads a sample chat. A subsequent explicit request proposes a tag through the approval gate, and that change is rejected. This demonstrates the configured path; it does not certify every provider or endpoint.
The published video combines edited actual interaction captures with actual Kiro evidence. It uses synthetic English narration, discloses that narration, and includes English captions. All sample records are fictional.
Test the contracts that make the template reusable
The project uses Vitest, property tests, shared storage contract tests, Playwright and axe. The recorded regressions include duplicate conversation IDs during import and Markdown role markers inside message bodies. Retaining those examples helps test the behavior the product promises.
For the video-link publication update, local typecheck, lint, 342 unit/property tests, build and 57 browser tests passed. The hosted CI run and Cloudflare deployment also passed. Browser coverage includes offline paths, keyboard interaction, provider mode and accessibility checks. These checks support the tested paths; they are not a claim that every possible archive or model was tested.
Tool attribution and what comes next
The development record includes Kiro-attributed implementation and reviews, plus Claude Code and Codex contributions. Codex handled the November 17 follow-up, performance work, evidence capture, video production and publication closeout described in KIRO_USAGE.md.
This article does not attribute every line, test run or media asset to Kiro. The project uses Kiro IDE, specs, steering, hooks and MCP. It does not claim use of Kiro Crew or Powers.
After the submission, the next useful step is feedback from developers trying the starter for a different local-first agent app. The source, concrete history and evidence are available in KIRO_USAGE.md.
Top comments (0)
Comments
No comments yet. Start the discussion.