Skip to content

Commit 5bacda9

Browse files
stefaniukstefaniuk
committed
fix(readme): enhance project description and structure for clarity and usability
1 parent 1dc550a commit 5bacda9

File tree

1 file changed

+125
-89
lines changed

1 file changed

+125
-89
lines changed

‎README.md‎

Lines changed: 125 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,92 @@
1-
<div align="center">
1+
# Prompt Files
22

3-
# 🤖 AI-assisted Development Prompt Files
3+
A curated, specification-first library of prompts, instruction packs, skills, and Copilot agents that keeps AI helpers aligned with the spec-kit operating model.
44

55
[![Spec-Kit](https://img.shields.io/badge/spec--kit-powered-blue?style=for-the-badge)](https://github.com/stefaniuk/promptfiles)
66
[![Licence](https://img.shields.io/badge/licence-MIT-green?style=for-the-badge)](LICENCE.md)
77
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge)](./.github/contributing.md)
88

9-
**A curated, specification-first library of prompts, instruction packs, skills, and Copilot agents**
9+
## Why this project exists
1010

11-
_Keep AI helpers aligned with the spec-kit operating model • Copy-and-paste reuse • Deterministic workflows_
11+
### Purpose
1212

13-
[Quick Start](#-quick-start) •
14-
[Features](#-why-use-this-library) •
15-
[Artefacts](#-featured-artefacts) •
16-
[Workflow](#-operational-workflow) •
17-
[Contributing](#-contributing)
13+
This library provides a central source of reusable prompts, instruction packs, skills, and Copilot agents for AI-assisted development workflows. It enables specification-driven development by keeping AI helpers aligned with a shared operating model.
1814

19-
</div>
15+
### Benefit to the user
2016

21-
---
17+
Teams gain consistent, deterministic automation across repositories. Copy-paste reuse makes onboarding faster, and governance gates ensure that specifications, code, and documentation stay synchronised.
2218

23-
## 🚀 Quick Start
19+
### Problem it solves
2420

25-
Get up and running in minutes:
21+
Without shared prompt files, AI assistants drift from agreed standards, produce inconsistent outputs, and lack deterministic validation. Teams end up reinventing the same prompts and struggling to maintain alignment across projects.
2622

27-
| Step | Action |
28-
| :---: | ------------------------------------------------------------------------------------------------------------------- |
29-
| **1** | ✂️ **Copy** the prompts or instruction packs you need straight into downstream repositories |
30-
| **2** | 📦 **Install** instructions by copying guidance into `.github/instructions` so Copilot inherits rules automatically |
31-
| **3** | 🤖 **Use** prompts under `.github/prompts` or agents under `.github/agents` to plan, spec, and review |
32-
| **4** | 🧪 **Validate** by running `make lint` and `make test` whenever you touch source material |
33-
| **5** | 🧠 **Document** architectural reasoning in `docs/adr` for future context |
23+
### How it solves it (high level)
3424

35-
---
25+
Prompts, agents, and skills are written directly against the spec-kit constitution. Instruction packs apply deterministic lint, test, and review rules. Every workflow leans on `make lint`, `make test`, and explicit governance gates, keeping behaviour measurable and testable.
3626

37-
## ✨ Why Use This Library
27+
## Quick start
3828

39-
<table>
40-
<tr>
41-
<td width="50%">
29+
### Prerequisites
4230

43-
### 📜 Specification-First Truth
31+
- Git
32+
- Make (GNU Make 3.82+)
33+
- A text editor (VS Code recommended for Copilot integration)
4434

45-
Prompts, agents, and skills are written directly against the spec-kit constitution, so code, docs, and governance remain synchronised.
35+
### Setup
4636

47-
### 🛡️ Consistent Guardrails
37+
```bash
38+
# Clone the repository
39+
git clone https://github.com/stefaniuk/promptfiles.git
40+
cd promptfiles
4841

49-
Instruction packs apply deterministic lint, test, and review rules across every repo, ensuring Copilot never drifts from agreed standards.
42+
# Configure the development environment
43+
make config
5044

51-
</td>
52-
<td width="50%">
45+
# Verify quality gates work
46+
make lint && make test
47+
```
5348

54-
### ⚙️ Deterministic Automation
49+
### First run
5550

56-
Every workflow leans on `make lint`, `make test`, and explicit governance gates, keeping behaviour measurable and testable.
51+
Get up and running in minutes:
5752

58-
### 📦 Copy-Ready Building Blocks
53+
| Step | Action |
54+
| :---: | ------------------------------------------------------------------------------------------------------------------- |
55+
| **1** | ✂️ **Copy** the prompts or instruction packs you need straight into downstream repositories |
56+
| **2** | 📦 **Install** instructions by copying guidance into `.github/instructions` so Copilot inherits rules automatically |
57+
| **3** | 🤖 **Use** prompts under `.github/prompts` or agents under `.github/agents` to plan, spec, and review |
58+
| **4** | 🧪 **Validate** by running `make lint` and `make test` whenever you touch source material |
59+
| **5** | 🧠 **Document** architectural reasoning in `docs/adr` for future context |
5960

60-
Everything is shippable by folder, making large organisations faster to onboard.
61+
**Expected output:** `make lint` and `make test` complete successfully with exit code 0.
6162

62-
</td>
63-
</tr>
64-
</table>
63+
## What it does
6564

66-
---
65+
### Key features
6766

68-
## 📦 Featured Artefacts
67+
- **Specification-first truth** — prompts, agents, and skills are written directly against the spec-kit constitution, so code, docs, and governance remain synchronised
68+
- **Consistent guardrails** — instruction packs apply deterministic lint, test, and review rules across every repo, ensuring Copilot never drifts from agreed standards
69+
- **Deterministic automation** — every workflow leans on `make lint`, `make test`, and explicit governance gates, keeping behaviour measurable and testable
70+
- **Copy-ready building blocks** — everything is shippable by folder, making large organisations faster to onboard
71+
- **Governance gates** — explicit checkpoints between specification and implementation
6972

70-
> **Tip:** Each pack is designed for copy-paste reuse. Pick what you need!
73+
### Non-goals
7174

72-
| Pack | Description |
73-
| :---------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
74-
| 🤖 **[.github/agents](.github/agents)** | Ready-to-run Copilot agents (analyze, checklist, clarify, constitution, implement, plan, specify, tasks, taskstoissues) tuned for spec-kit ceremonies |
75-
| 💬 **[.github/prompts](.github/prompts)** | Focused prompt files for documentation reviews, governance gates, tests, and refactoring support |
76-
| 📋 **[.github/instructions](.github/instructions)** | Coding standards and best practice packs scoped by file glob so Copilot always sees the right rules |
77-
| 🧠 **[.github/skills](.github/skills)** | Bundled instructions plus helper assets that extend Copilot's capabilities for niche workflows |
78-
| 📝 **[.specify/templates](.specify/templates)** | Seed specs, plans, and tasks for new features |
79-
| 📄 **[docs/adr/adr-template.md](docs/adr/adr-template.md)** | Opinionated ADR template aligned with spec-kit identifiers |
75+
- This library does not implement the underlying spec-kit framework itself
76+
- It does not provide runtime execution environments for prompts
77+
- It is not a replacement for language-specific linters or test frameworks
8078

81-
---
79+
## How it solves the problem
8280

83-
## 🔄 Operational Workflow
81+
The spec-kit lifecycle follows a structured flow:
8482

85-
The spec-kit lifecycle: **discover** the right prompt → **ground** it in a specification → **automate** every validation step.
86-
87-
### 📊 Workflow Diagram
83+
1. **Discover** the right prompt from the library
84+
2. **Ground** it in a specification using agents like `/speckit.specify`
85+
3. **Plan** the implementation with `/speckit.plan`
86+
4. **Generate tasks** with `/speckit.tasks`
87+
5. **Implement** with `/speckit.implement`
88+
6. **Review** with governance gates (`/review.speckit-documentation`, `/review.speckit-code`, `/review.speckit-test`)
89+
7. **Automate** every validation step with `make lint` and `make test`
8890

8991
```mermaid
9092
flowchart TD
@@ -129,7 +131,15 @@ flowchart TD
129131
class specifyNote,checklistNote,planNote,tasksNote,implementNote,reviewDocsNote note;
130132
```
131133

132-
### 📤 Sync Prompt Files
134+
## How to use
135+
136+
### Configuration
137+
138+
No additional configuration is required beyond the initial setup. The library uses convention over configuration with sensible defaults.
139+
140+
### Common workflows
141+
142+
#### Sync prompt files to a target repository
133143

134144
```bash
135145
make apply dest=/absolute/path/to/target
@@ -147,7 +157,7 @@ make apply dest=/absolute/path/to/target
147157

148158
> **Next step:** Review git status in the target repo, commit, and run `make lint && make test`
149159
150-
### 📊 Estimate Context Window Usage
160+
#### Estimate context window usage
151161

152162
```bash
153163
# Default: scan Copilot prompt files
@@ -166,9 +176,7 @@ The report shows:
166176
- **No IDs** — counts with identifiers like `[ID-<prefix>-NNN]` stripped
167177
- **Usage %** — context window usage (200K baseline)
168178

169-
### 🛡️ Governance Gates
170-
171-
Explicit checkpoints between specification and implementation:
179+
#### Run governance gates
172180

173181
| Gate | Command | Purpose |
174182
| :--------------------- | :------------------------------ | :-------------------------------------------- |
@@ -188,9 +196,20 @@ Explicit checkpoints between specification and implementation:
188196

189197
</details>
190198

191-
---
199+
### Examples
200+
201+
#### Featured artefacts
202+
203+
| Pack | Description |
204+
| :---------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
205+
| 🤖 **[.github/agents](.github/agents)** | Ready-to-run Copilot agents (analyze, checklist, clarify, constitution, implement, plan, specify, tasks, taskstoissues) tuned for spec-kit ceremonies |
206+
| 💬 **[.github/prompts](.github/prompts)** | Focused prompt files for documentation reviews, governance gates, tests, and refactoring support |
207+
| 📋 **[.github/instructions](.github/instructions)** | Coding standards and best practice packs scoped by file glob so Copilot always sees the right rules |
208+
| 🧠 **[.github/skills](.github/skills)** | Bundled instructions plus helper assets that extend Copilot's capabilities for niche workflows |
209+
| 📝 **[.specify/templates](.specify/templates)** | Seed specs, plans, and tasks for new features |
210+
| 📄 **[docs/adr/adr-template.md](docs/adr/adr-template.md)** | Opinionated ADR template aligned with spec-kit identifiers |
192211

193-
## 🧭 Prompt Naming Convention
212+
#### Prompt naming convention
194213

195214
Prompts use a **prefix + category + verb** convention to keep fuzzy search fast and predictable:
196215

@@ -202,51 +221,68 @@ Prompts use a **prefix + category + verb** convention to keep fuzzy search fast
202221
| `review.` | Review and audit prompts | `review.speckit-code.prompt.md` |
203222
| `util.` | Operational utilities | `util.gh-pr-review.prompt.md` |
204223

205-
## 🗺️ Roadmap
206-
207-
<details>
208-
<summary><strong>📝 New Prompts</strong></summary>
224+
## Resources
209225

210-
- `architecture-review.prompt` — architect for flow
211-
- `migrate-from-[tech A]-to-[tech B].prompt`
226+
| Resource | Link |
227+
| :------------------ | :------------------------------------------------------------------------------------------- |
228+
| Custom Prompts | [VS Code Docs](https://code.visualstudio.com/docs/copilot/customization/prompt-files) |
229+
| Custom Instructions | [VS Code Docs](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) |
230+
| Custom Agents | [VS Code Docs](https://code.visualstudio.com/docs/copilot/customization/custom-agents) |
231+
| Custom Skills | [VS Code Docs](https://code.visualstudio.com/docs/copilot/customization/agent-skills) |
232+
| Awesome Copilot | [GitHub](https://github.com/github/awesome-copilot) |
212233

213-
</details>
214-
<details>
215-
<summary><strong>🔧 Workflow Prompts</strong></summary>
234+
## Contributing
216235

217-
- **Release notes** — changelog entries grouped by spec identifiers
236+
We welcome contributions! See [.github/contributing.md](.github/contributing.md) for the full guide.
218237

219-
</details>
238+
### Development setup
220239

221-
---
240+
```bash
241+
git clone https://github.com/stefaniuk/promptfiles.git
242+
cd promptfiles
243+
make config
244+
```
222245

223-
## 🤝 Contributing
246+
### Quality commands
224247

225-
We welcome contributions! See [contributing.md](./.github/contributing.md) for the full guide.
248+
```bash
249+
make lint # Run linters (file format, markdown format, markdown links)
250+
make test # Run tests
251+
```
226252

227-
**Quick checklist:**
253+
### Quick checklist
228254

229255
1. **Raise an issue or PR** describing your planned changes
230256
2. **Keep artefacts in sync** — specs, plans, tasks, and docs must align
231257
3. **Run quality gates** — `make lint && make test` before opening a PR
232258
4. **Follow the constitution** and NHS Engineering guidance
233259

234-
---
260+
## Repository layout
235261

236-
## 📚 Resources
262+
- `.github/agents/` — Copilot agent definitions for spec-kit ceremonies
263+
- `.github/instructions/` — Coding standards by language/framework
264+
- `.github/prompts/` — Task-specific prompt files
265+
- `.github/skills/` — Bundled capabilities with supporting assets
266+
- `.specify/` — Spec-kit templates and project constitution
267+
- `docs/adr/` — Architecture decision records
268+
- `scripts/` — Build and utility scripts
237269

238-
| Resource | Link |
239-
| :------------------ | :------------------------------------------------------------------------------------------- |
240-
| Custom Prompts | [VS Code Docs](https://code.visualstudio.com/docs/copilot/customization/prompt-files) |
241-
| Custom Instructions | [VS Code Docs](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) |
242-
| Custom Agents | [VS Code Docs](https://code.visualstudio.com/docs/copilot/customization/custom-agents) |
243-
| Custom Skills | [VS Code Docs](https://code.visualstudio.com/docs/copilot/customization/agent-skills) |
244-
| Awesome Copilot | [GitHub](https://github.com/github/awesome-copilot) |
270+
## Roadmap
271+
272+
<details>
273+
<summary><strong>📝 New Prompts</strong></summary>
274+
275+
- `architecture-review.prompt` — architect for flow
276+
- `migrate-from-[tech A]-to-[tech B].prompt`
277+
278+
</details>
279+
<details>
280+
<summary><strong>🔧 Workflow Prompts</strong></summary>
245281

246-
---
282+
- **Release notes** — changelog entries grouped by spec identifiers
247283

248-
<div align="center">
284+
</details>
249285

250-
**Made with ❤️ for specification-driven development**
286+
## Licence
251287

252-
</div>
288+
This project is licensed under the MIT Licence. See [LICENCE.md](LICENCE.md) for details.

0 commit comments

Comments
 (0)