Important
SparkWell is at a very early stage. Its methodology and tooling are under active development, and its underlying ideas have not yet been thoroughly validated through broad practical use. Expect significant changes. You are welcome to try it and share feedback, use cases, and challenges through GitHub issues.
Build and evolve software through shared, durable intent.
SparkWell gives humans and AI a durable, reviewable representation of software intent for building and evolving software together.
Software engineering is not only about generating code. It is also about understanding, reviewing, evolving, and maintaining software over time.
Coding agents make implementation dramatically faster, but speed creates a new imbalance: our ability to generate software can outpace our ability to understand it. Important decisions disappear into temporary conversations, implementation grows faster than people can review it, and future contributors must reconstruct intent from code and fragmented documentation.
AI conversations are temporary. Design discussions, clarifications, and decisions can disappear when a session ends, forcing future humans and agents to reconstruct the same understanding.
SparkWell captures implementation-critical intent in persistent project artifacts rather than relying on conversation history.
AI can generate implementation faster than humans can review it line by line. As systems grow, implementation alone becomes an increasingly expensive review surface.
SparkWell lets people review software intent and concept boundaries before implementation is generated.
Implementation records how software currently works, but often loses why responsibilities, constraints, interactions, and boundaries exist.
Sparks preserve that design intent as the system evolves across refactors, frameworks, platforms, and rewrites.
Modern AI workflows can increasingly treat implementation as a black box.
People describe desired outcomes.
AI generates implementation.
When evaluation focuses only on observable correctness, large portions of the generated implementation may never be deeply understood.
This raises several fundamental questions:
- Is implementation alone a sufficient artifact for understanding a software system?
- What should people review when implementation becomes too large to examine in detail?
- What should AI understand before generating or changing implementation?
- Can humans and AI collaborate through something more durable than implementation alone?
SparkWell answers these questions by making software intent a first-class artifact alongside implementation.
SparkWell introduces a Spark as an additional software engineering artifact between Requirements and Engineering Artifacts. A Spark captures the shared software intent of one meaningful concept for humans and AI to understand, clarify, and review together.
Requirements
│
▼
Human + AI Collaboration
│
▼
Spark
(Shared Software Intent)
│
Human + AI Collaboration
│
▼
Engineering Artifacts
├── Source Code
├── Tests
├── Documentation
├── Diagrams
└── Platform-specific Implementations
A Spark is neither a compressed request nor an exhaustive design dossier. It captures the minimum sufficient intent for one concept: the decisions whose absence would force a reviewer or implementer to guess material behavior, ownership, invariants, constraints, or relationships. Each decision belongs in one authoritative Spark; related Sparks reference that owner instead of repeating it.
Sparks can exist at different levels of abstraction. Bundled SparkWell workflows currently support three standardized kinds: Domain Models, Services, and modular UI Components. Projects may define another kind only by supplying its semantics, document rules, design rules, and target applicability.
Spark IDs may use -model, -service, or -ui as readability hints. These suffixes are optional; the kind field remains authoritative and workflows do not depend on suffixes. Human-readable names remain natural.
domain-model represents independently meaningful domain concepts with durable field semantics, invariants, lifecycle, and relationships. service represents independently meaningful capabilities, concept-level inputs and outputs, and failure behavior across a boundary. ui-component represents a modular interface boundary with user-facing behavior, state, interactions, accessibility intent, and optional child composition. A root UI Component may realize the application shell, window, page, route, or another platform entry surface.
Each Spark is stored as a Spark Document with two complementary parts:
- concise frontmatter for stable identity and relationships;
- a concise natural-language body for the concept's owned intent.
The Spark Document is the durable design contract for that concept. It evolves when the software intent changes, not every time code is refactored, dependencies are upgraded, or implementation structure moves.
Ordinary engineering choices remain free unless they are themselves part of the software intent. A Spark does not prescribe a language, framework, class, file, or test structure by default. It may be realized by source code, tests, documentation, diagrams, and platform-specific implementations, while one artifact may realize several Sparks.
This separation allows implementations to evolve while the concept's identity and intent remain recognizable across technologies and over time.
SparkWell is opt-in. Ordinary questions, coding, debugging, refactoring, and testing use the coding agent's normal workflow and do not create or update Sparks.
Invoke /spark-design to clarify a requested change. It first presents a concise Spark Proposal in chat, listing the Sparks to create and their summaries plus existing Sparks to evolve and why. It does not modify files before confirmation.
When the host provides a decision UI, choose Revise, Finalize, or Cancel; choosing Revise opens a prompt for comments. Otherwise, reply Revise: <comments>, Finalize, or Cancel. Finalized documents then receive a second human review before any implementation workflow begins.
After review, invoke later workflows independently:
| Workflow | Responsibility | Does not own |
|---|---|---|
/spark-impl |
Creates or updates target engineering artifacts using the selected profile and implementation packs | Spark design or test authoring |
/spark-test |
Derives behavioral scenarios, creates or updates test artifacts, and reports verified and unverified intent | Spark design or production runtime changes |
Each slash command activates only that workflow for the current request. A decision collected by the host UI, or a direct fallback control for the latest Spark Proposal, is the only limited continuation. Workflows never activate automatically or chain into one another.
SparkWell provides the shared realization process, not a universal project architecture or interface format. Profiles and guidance are project-owned inputs maintained manually or with ordinary coding-agent assistance. /spark-impl follows Sparks, profile routing and Pack configuration, project guidance, selected Packs, and native architecture; it does not choose MVC, MVVM, state management, persistence, synchronization, module structure, or a wire protocol on the project's behalf.
Project-wide system shape and ownership context that may affect Spark boundaries belongs in the project-owned .sparkwell/design-context.md. /spark-design reads it before proposing concepts; profile guidance remains responsible for target-specific implementation architecture.
Reusable technology behavior is distributed as optional implementation packs. Install a bundled pack explicitly, then activate it only in profiles that need it. For example, sparkwell init --pack openapi installs OpenAPI 3.1 producer, server, client, and test guidance without making OpenAPI part of SparkWell Core or enabling it for every profile.
When implementation or testing reveals missing or contradictory intent, the workflow stops and identifies /spark-design as the explicit next command. It does not invoke that workflow, invent product behavior in code, or weaken a test.
SparkWell requires Node.js 20 or later and has no runtime package dependencies.
git clone https://github.com/junvwang/SparkWell.git
cd SparkWell
npm link
cd ../MyProject
sparkwell initOptional implementation packs are installed separately:
sparkwell init --pack openapiThen explicitly invoke a workflow, for example:
/spark-design Design a todo list where people can add todos and mark them complete.
Review the Spark Proposal, choose Finalize in the decision UI or reply Finalize when no UI is available, then review the generated Spark Documents before separately invoking /spark-impl or /spark-test as needed.
Before the first new runtime realization, copy the profile placeholder from .sparkwell/config.yaml and maintain its referenced file under .sparkwell/guidance/. Complete the consequential architecture decisions there before invoking /spark-impl.
See the Project Setup Flow for the complete order and ownership of these files.
GitHub Copilot is the default adapter. SparkWell also supports Claude Code, AGENTS.md-compatible agents, multi-agent projects, and an agent-neutral initialization mode.
See the detailed usage guide for installation, adapters, configuration, workflow usage, safety behavior, and the complete CLI reference.
| Path | Purpose |
|---|---|
core/ |
Canonical SparkWell instructions and project contracts |
skills/ |
Agent-neutral design, configuration, implementation, testing, and visualization workflows |
packs/ |
Optional reusable technology-specific implementation and test guidance |
adapters/ |
Declarative mappings to coding-agent instruction and skill locations |
scripts/ |
Dependency-free CLI and initialization engine |
docs/README.md |
Documentation map and source-of-truth guide |
docs/usage.md |
Detailed installation and usage reference |
docs/implementation-packs.md |
Pack boundary, activation, OpenAPI example, and migration guide |
test/ |
CLI, projection, migration, safety, and methodology integrity tests |
SparkWell is in early development. The core Spark specification, standardized Domain Model, Service, and UI Component kinds, project implementation guidance, explicit design/configuration/implementation/testing workflows, realization provenance, multi-agent adapters, and an optional OpenAPI implementation pack are available today.
The methodology and tooling will continue to evolve through practical use and feedback while keeping existing project content safe and version controlled. See the current status and roadmap for the mutable project snapshot.
The name is inspired by the Spark in the Transformers universe: the enduring identity that remains even when a Transformer changes or rebuilds its body.
Software has a similar continuity. Implementations evolve. Languages and frameworks change. Systems may be rewritten. Yet the intent of a software concept - why it exists, what it owns, how it behaves, and how it relates to other concepts - should remain recognizable.
A Spark is not another implementation. It is the design identity that should survive every implementation.
Questions, critical feedback, documentation improvements, adapter support, workflow improvements, and code contributions are welcome through GitHub issues and pull requests.
When changing a shared skill, keep it agent-neutral and preserve compatibility across supported coding agents.
SparkWell is licensed under the MIT License.