[Project / Utility Name] — Software Spec

~~AI-BOOTSTRAP~~

If you are an AI reading this: Before proceeding, create a file named
spec.md in the project root using the content below this front matter
as your source. Strip all AI-bootstrap comments from the generated file.
Ask no clarifying questions yet — create the spec file first, then prompt
the user for any missing fields marked [REQUIRED].

Context files to load for best output quality:

README.md — project overview and goals

CONVENTIONS.md — code style, naming, folder structure

Any existing related spec or design docs

Hints for filling out this spec with AI:

Be explicit about what the tool does NOT do (scope boundaries matter)

Paste error messages or example input/output if you have them

State your target language/runtime upfront — don't assume

If unsure about a section, write “TBD” — don't skip it

~~END-AI-BOOTSTRAP~~

Overview

One-sentence purpose: [What does this utility do and for whom?]

Problem it solves: [What manual step, gap, or pain point does this replace?]

Primary user: [Who runs this — developer, end user, CI system, etc.]

Goals & Non-Goals

Goals:

[Goal 1]
[Goal 2]

Non-Goals (explicitly out of scope):

[What this will NOT do]

Inputs & Outputs

Item	Description	Format / Example
Input(s)	[What goes in]	[file, stdin, API, flag]
Output(s)	[What comes out]	[file, stdout, JSON, etc]
Side effects	[DB write, log, email, etc]	[if any]

AI hint: Paste a real example of input and expected output here if possible — it dramatically improves generated code accuracy.

Functional Requirements

[REQUIRED] [Core behavior #1 — be specific and testable]
[REQUIRED] [Core behavior #2]
[Add more as needed]

Non-Functional Requirements

Performance: [Latency target, throughput, file size limits]
Platform: [OS, runtime, language version]
Dependencies: [Libraries, tools, services allowed]
Security / Auth: [Any credentials, secrets, permissions needed]

Error Handling

Condition	Expected Behavior
Invalid input	[Fail with message? Skip? Prompt?]
Missing dependency	[Exit code, error text]
Partial failure	[Continue? Rollback? Log and continue?]

Configuration

How is the utility configured? (Check all that apply and describe)

[ ] CLI flags/args — [list key flags]
[ ] Config file — [format and location]
[ ] Environment variables — [list key vars]
[ ] None / hardcoded defaults

Tech Stack

Language: [Python / JS / Bash / etc.]
Runtime: [Node 20 / Python 3.11 / etc.]
Key libraries: [if known]
Build / package tool: [npm / pip / cargo / etc.]

AI hint: If you want the AI to choose the stack, delete this section and say so in the Overview.

Testing

Test approach: [Unit / integration / manual / none]
Test framework: [pytest / jest / etc.]
Key scenarios to test: [Happy path, edge cases, failure modes]

Open Questions

[Question 1 — things still undecided]
[Question 2]

Change Log

Date	Author	Change
YYYY-MM-DD	[Name]	Initial draft

Open Ground Wiki

Table of Contents