Mono Spec Kit

Purpose

Create a reusable Markdown feature specification in documents/ before implementation. The document keeps web and api requirements in one shared context while still separating each surface clearly, preventing fragmented planning between frontend and backend work.

When to Use

Use this skill when the user asks to:

• Create a feature spec, 기능 명세, or implementation-ready requirements document.
• Assetize planned functionality as Markdown in documents/.
• Define web and api behavior together before coding.
• Specify architecture, folder structure, UI/UX, API contracts, data model, auth, or tests for a feature.
• Prepare a single source of context for simultaneous web and api development.

Do not use this skill for pure code implementation unless the user also asks to create or update the feature spec.

Output

Create or update one Markdown file under documents/:

documents/<feature-slug>.md

Use a lowercase kebab-case slug based on the feature name. If a related spec already exists, update it instead of creating a duplicate.

Procedure

1. Clarify the feature boundary.
   • Identify the user goal, target users, core workflow, and expected outcome.
   • Separate web scope, api scope, shared data/state, and out-of-scope items.
   • If the feature boundary is ambiguous, ask only the minimum questions needed to avoid writing a misleading spec.
2. Inspect the current project context.
   • Check existing app/package structure before proposing paths.
   • Prefer existing architecture, naming, design patterns, and package conventions.
   • Note any existing files, modules, or routes the feature should extend.
3. Research official documentation.
   • Use web search or webpage fetching for official docs when the feature depends on a framework, library, protocol, API, or service.
   • Prefer official documentation over blog posts or examples.
   • Record only links that directly influence the spec.
   • If web access is unavailable, state that and mark the reference as needing confirmation.
4. Draft the Markdown spec.
   • Keep web and api sections separate, but include cross-surface contracts in the same document.
   • Be concrete about architecture, folder structure, UI/UX composition, API routes, request/response shapes, validation, auth, error states, and tests.
   • Use implementation-ready language without over-prescribing incidental code details.
5. Save the spec.
   • Create documents/ if it does not exist.
   • Save the file as documents/<feature-slug>.md.
   • Do not place feature specs outside documents/ unless the user explicitly overrides this.
6. Validate completeness.
   • Confirm the file exists in documents/.
   • Confirm web and api are both covered or explicitly marked as not applicable.
   • Confirm official documentation references are included when relevant.
   • Confirm open questions are listed instead of hidden inside assumptions.

Decision Points

• If the user asks for web-only or api-only scope, still include a short counterpart section explaining why the other side is not affected.
• If the feature changes shared contracts, prioritize API contract and data model clarity before UI detail.
• If implementation details conflict with existing project conventions, follow the repository conventions and call out the tradeoff.
• If official docs disagree with current project usage, document the difference and recommend the lower-risk project-compatible path.
• If the request is too broad, create a parent spec with subfeatures and an implementation sequence rather than one vague document.

Required Document Template

Use this structure unless the user requests a different format:

# <Feature Name>

## Overview

Briefly describe the feature, its users, and the outcome it enables.

## Goals

- <Goal 1>
- <Goal 2>

## Non-Goals

- <Explicitly excluded behavior>

## User Scenarios

- As a <user>, I want <capability>, so that <outcome>.

## Integrated Web/API Context

Explain how web screens, api routes, data, auth, and state transitions work together.

## Web Specification

### Routes and Screens

- `<route>`: <screen purpose>

### UI/UX Composition

- Layout: <structure>
- Components: <component list>
- States: loading, empty, error, success, disabled, optimistic updates
- Accessibility: keyboard behavior, labels, focus, announcements

### Client State and Data Fetching

- Source of truth: <server/client/cache>
- Fetch/mutation flow: <flow>
- Cache invalidation or refresh behavior: <behavior>

### Web Folder Structure

```text
apps/web/src/...
```

## API Specification

### Endpoints

| Method | Path       | Auth     | Purpose          |
| ------ | ---------- | -------- | ---------------- |
| GET    | `/example` | Required | Example endpoint |

### Request/Response Contracts

```json
{
  "example": true
}
```

### Validation and Errors

- Validation rules: <rules>
- Error responses: <status and body>

### API Folder Structure

```text
apps/api/src/...
```

## Data Model

- Entities, fields, relationships, indexes, and migration notes.

## Auth and Permissions

- Required user/session state.
- Role or ownership checks.

## Architecture Notes

- Cross-package dependencies.
- Shared UI or utility packages.
- Background jobs, external services, or integration boundaries.

## Testing Strategy

- Unit tests
- Integration tests
- E2E tests
- Manual verification

## Implementation Checklist

- [ ] Web structure created
- [ ] API structure created
- [ ] Data model updated
- [ ] Contracts validated
- [ ] Tests added or updated
- [ ] Official docs reviewed

## Official References

- [Official doc title](https://example.com): <why it matters>

## Open Questions

- <Question or decision still needed>

Quality Bar

A finished spec must be specific enough that a coding agent can implement the feature without rediscovering the main product, web, and api context. It should include concrete routes, files, contracts, states, validation rules, and test expectations, while clearly marking assumptions and open questions.