PhantomSpec

Inspiration

Every developer has encountered "haunted" legacy codebases—undocumented functions, tangled dependencies, and mysterious bugs that nobody dares to touch. Inspired by the Kiroween theme and the power of spec-driven development in Kiro IDE, we wanted to build a tool that doesn't just patch old code, but systematically resurrects and modernizes it using structured specifications and autonomous agent hooks.

What it does

PhantomSpec is an AI-powered spec-to-code refactoring and workflow automation engine. It analyzes legacy repositories, extracts hidden business logic into clean, human-readable specifications (requirements.md and design.md), and automatically generates modernized, type-safe full-stack components alongside comprehensive unit tests.

We also implemented a custom Refactoring Confidence Score ($RCS$) to evaluate code readiness before automated deployment:

$$RCS = \frac{C_{test} \times (1 - D_{coupling})}{\ln(L_{cyclomatic} + e)}$$

Where $C_{test}$ represents test coverage, $D_{coupling}$ measures module coupling, and $L_{cyclomatic}$ is the cyclomatic complexity of the target module.

How we built it

We built the entire project using Kiro IDE and Kiro CLI, leaning heavily into spec-driven development:

• Specs First: Instead of jumping straight into boilerplate code, we used Kiro to generate structured requirements.md, design.md, and tasks.md files. This kept our architecture clean and deterministic.
• Agent Hooks: We configured Kiro Agent Hooks to automatically trigger linting, type-checking, and test generation whenever a specification or core module was updated.
• Frontend & Backend: Built with TypeScript, React, Next.js, and Tailwind CSS on the frontend, paired with a Node.js and Python (FastAPI) backend for AST (Abstract Syntax Tree) parsing.
• Cloud & Database: Hosted on AWS using PostgreSQL for storing spec histories and project states.

Challenges we ran into

One of the biggest hurdles was keeping context windows manageable when parsing deeply nested legacy files. Initially, feeding raw multi-file dependencies directly into the prompt caused hallucinations. We solved this by building an AST pre-processor that strips out boilerplate and feeds Kiro structured dependency graphs, allowing the spec generator to stay laser-focused.

Accomplishments that we're proud of

• Achieving a fully automated flow from raw legacy code to a validated Kiro spec and working TypeScript output in under 30 seconds.
• Designing seamless Kiro Agent Hooks that eliminated manual test writing during the hackathon.
• Creating an intuitive, dark-themed UI that visualizes code complexity metrics in real time.

What we learned

Working with Kiro fundamentally shifted how we approach software engineering. Moving from "prompt-driven coding" to spec-driven development proved that spending 20% more time refining the specification cuts debugging time by over 70%.

What's next for PhantomSpec

Next, we plan to add multi-repository support, deeper integration with Kiro CLI for automated CI/CD pipelines, and one-click pull request generation directly for GitHub and GitLab.

Built With

• amazon-web-services
• docker
• fastapi
• git
• github
• javascript
• kiro
• kiro-cli
• kiro-ide
• nextjs
• node.js
• postgresql
• python
• react
• tailwindcss
• typescript