|
1 | | -<div align="center"> |
| 1 | +# agents-smith |
2 | 2 |
|
3 | | -<img src="docs/assets/banner.svg" alt="agents-smith" width="100%"/> |
4 | | - |
5 | | -<br/><br/> |
6 | | - |
7 | | -[![Contributors][contributors-shield]][contributors-url] |
8 | | -[![Forks][forks-shield]][forks-url] |
9 | | -[![Stargazers][stars-shield]][stars-url] |
10 | | -[![Issues][issues-shield]][issues-url] |
11 | | -[![MIT License][license-shield]][license-url] |
12 | | -[](https://nullhack.github.io/agents-smith/coverage/) |
13 | | -[](https://github.com/nullhack/agents-smith/actions/workflows/ci.yml) |
14 | | -[](https://www.python.org/downloads/) |
15 | | - |
16 | | -**Pair program with AI, the right way.** |
17 | | - |
18 | | -</div> |
19 | | - |
20 | | ---- |
21 | | - |
22 | | -smith is an AI pair programming platform that connects standardised agent configurations to any project directory — and disconnects cleanly when done. It ships with a complete delivery workflow: structured flows for discovery, planning, TDD development, review, and release, powered by specialised agents (Product Owner, Architect, Engineer, Reviewer, and more). |
23 | | - |
24 | | ---- |
| 3 | +Clone AI agent configurations (AGENTS.md, .opencode/, .flowr/, .templates/) to any project. |
25 | 4 |
|
26 | 5 | ## Install |
27 | 6 |
|
28 | 7 | ```bash |
29 | 8 | pip install agents-smith |
30 | 9 | ``` |
31 | 10 |
|
32 | | -Or clone for development: |
33 | | - |
34 | | -```bash |
35 | | -git clone https://github.com/nullhack/agents-smith |
36 | | -cd agents-smith |
37 | | -curl -LsSf https://astral.sh/uv/install.sh | sh # skip if uv is already installed |
38 | | -uv sync --all-extras |
39 | | -``` |
40 | | - |
41 | | ---- |
42 | | - |
43 | 11 | ## Usage |
44 | 12 |
|
45 | | -### Connect |
46 | | - |
47 | | -Write agentic files (agents, skills, knowledge, flows, templates) into any project directory: |
48 | | - |
49 | | -```bash |
50 | | -smith connect # from bundled template (no network needed) |
51 | | -smith connect --from PATH # from a local directory |
52 | | -smith connect --from URL # from a remote tarball |
53 | | -smith connect --overwrite # replace existing smith-managed files |
54 | | -``` |
55 | | - |
56 | | -### Status |
57 | | - |
58 | | -Check what smith has connected to your project: |
59 | | - |
60 | | -```bash |
61 | | -smith status # human-readable output |
62 | | -smith status --json # machine-readable output |
63 | | -``` |
64 | | - |
65 | | -### Update |
66 | | - |
67 | | -Re-sync agentic files from the connected source: |
68 | | - |
69 | 13 | ```bash |
70 | | -smith update # from the same source used at connect time |
71 | | -smith update --from PATH # from a different local source |
72 | | -``` |
| 14 | +# Clone — downloads templates from the default source (temple8) |
| 15 | +smith clone |
73 | 16 |
|
74 | | -### Disconnect |
| 17 | +# Clone from a specific source |
| 18 | +smith clone --source github:myorg/my-template |
| 19 | +smith clone --source /path/to/local/template |
| 20 | +smith clone --source https://example.com/template.zip |
75 | 21 |
|
76 | | -Remove all smith-managed files and gitignore entries. User-tracked files are never touched: |
| 22 | +# Clone and overwrite existing files |
| 23 | +smith clone --overwrite |
77 | 24 |
|
78 | | -```bash |
79 | | -smith disconnect |
| 25 | +# Purge — removes files listed in the smith-managed .gitignore section |
| 26 | +smith purge |
80 | 27 | ``` |
81 | 28 |
|
82 | | ---- |
83 | | - |
84 | | -## What you get |
85 | | - |
86 | | -When you run `smith connect`, the following is written into your project: |
87 | | - |
88 | | -| Path | Contents | |
89 | | -|------|----------| |
90 | | -| `AGENTS.md` | Agent routing, session protocol, artifact conventions | |
91 | | -| `.opencode/agents/` | Agent identity definitions (Product Owner, Architect, Engineer, Reviewer, etc.) | |
92 | | -| `.opencode/skills/` | Step-by-step skill definitions for every workflow state | |
93 | | -| `.opencode/knowledge/` | Curated knowledge files (TDD, DDD, architecture, requirements, design, etc.) | |
94 | | -| `.flowr/flows/` | YAML state machine definitions (delivery, TDD cycle, review gate, setup, etc.) | |
95 | | -| `.templates/` | Artifact templates (ADR, feature files, changelog, interview notes, etc.) | |
| 29 | +## Source resolution |
96 | 30 |
|
97 | | -### Agents |
| 31 | +1. `--source` CLI flag (highest priority) |
| 32 | +2. `[tool.smith] source = "..."` in pyproject.toml |
| 33 | +3. Default: `github:nullhack/temple8` |
98 | 34 |
|
99 | | -Six specialised agents, each owning a phase of the delivery flow: |
| 35 | +## How it works |
100 | 36 |
|
101 | | -| Agent | Role | |
102 | | -|-------|------| |
103 | | -| **Product Owner** | Scope discovery, feature selection, acceptance | |
104 | | -| **Domain Expert** | Ubiquitous language, domain modeling, glossary | |
105 | | -| **Architect** | System design, ADRs, context maps, review | |
106 | | -| **Software Engineer** | TDD implementation, refactoring, merging | |
107 | | -| **Reviewer** | Adversarial review (design, structure, conventions) | |
108 | | -| **Design Agent** | Visual identity, colors, assets | |
| 37 | +**clone**: Downloads AGENTS.md, .opencode/, .flowr/, .templates/ from the source. Skips any file or directory that already exists unless `--overwrite` is set. Adds a `# smith managed` section to .gitignore listing what was written. |
109 | 38 |
|
110 | | -### Flows |
| 39 | +**purge**: Reads the smith-managed section in .gitignore and deletes every file/directory listed there. Does not remove the .gitignore section itself. |
111 | 40 |
|
112 | | -Workflow state machines powered by [flowr](https://pypi.org/project/flowr/): |
| 41 | +## .gitignore section |
113 | 42 |
|
114 | | -| Flow | Purpose | |
115 | | -|------|---------| |
116 | | -| `delivery-flow` | End-to-end feature delivery (select → specify → implement → review → accept) | |
117 | | -| `tdd-cycle-flow` | Red-green-refactor loop within a feature | |
118 | | -| `review-gate-flow` | Three-tier review (design → structure → conventions) | |
119 | | -| `setup-project-flow` | Initialise a new project from template | |
120 | | -| `discovery-flow` | Stakeholder interviews and product scoping | |
121 | | -| `planning-flow` | Feature breakdown and BDD specification | |
122 | | -| `architecture-flow` | System design and context mapping | |
123 | | -| `post-mortem-flow` | Incident analysis and lessons | |
124 | | - |
125 | | -### Knowledge |
126 | | - |
127 | | -Curated research summaries covering TDD, DDD, architecture patterns, SOLID, test design, code review, versioning, and more. Agents load these progressively — key takeaways for quick reference, full documents for detailed work. |
128 | | - |
129 | | ---- |
130 | | - |
131 | | -## Development |
132 | | - |
133 | | -```bash |
134 | | -uv run task test # full suite + coverage |
135 | | -uv run task test-fast # fast, no coverage (TDD loop) |
136 | | -uv run task lint # ruff format + check |
137 | | -uv run task static-check # pyright type checking |
138 | | -uv run task run # run smith |
139 | | -uv run task doc-build # build API docs + coverage report |
140 | | -uv run task release-check # lint + typecheck + test + docs |
141 | 43 | ``` |
142 | | - |
143 | | -### Updating the bundled template |
144 | | - |
145 | | -The `smith/data/` directory ships with a bundled template. To sync it from the upstream [temple8](https://github.com/nullhack/temple8) repository: |
146 | | - |
147 | | -```bash |
148 | | -./scripts/update-bundle.sh |
| 44 | +# smith managed |
| 45 | +AGENTS.md |
| 46 | +.opencode/ |
| 47 | +.flowr/ |
| 48 | +.templates/ |
| 49 | +# end smith managed |
149 | 50 | ``` |
150 | 51 |
|
151 | | ---- |
152 | | - |
153 | | -## Documentation |
154 | | - |
155 | | -- **[Product Definition](docs/spec/product_definition.md)** — what smith is, who it's for, quality attributes |
156 | | -- **[System Overview](docs/spec/system.md)** — architecture, domain model, module structure, constraints |
157 | | -- **[Glossary](docs/spec/glossary.md)** — living domain glossary |
158 | | -- **[Technical Design](docs/spec/technical_design.md)** — hexagonal architecture, contracts, C4 diagrams |
159 | | -- **[Context Map](docs/spec/context_map.md)** — bounded contexts and integration points |
160 | | -- **[Branding](docs/branding.md)** — visual identity, voice, release naming convention |
161 | | - |
162 | | ---- |
163 | | - |
164 | | -## License |
165 | | - |
166 | | -MIT — see [LICENSE](LICENSE). |
167 | | - |
168 | | -**Author:** [@nullhack](https://github.com/nullhack) · [Documentation](https://nullhack.github.io/agents-smith) |
169 | | - |
170 | | -<!-- MARKDOWN LINKS --> |
171 | | -[contributors-shield]: https://img.shields.io/github/contributors/nullhack/agents-smith.svg?style=for-the-badge |
172 | | -[contributors-url]: https://github.com/nullhack/agents-smith/graphs/contributors |
173 | | -[forks-shield]: https://img.shields.io/github/forks/nullhack/agents-smith.svg?style=for-the-badge |
174 | | -[forks-url]: https://github.com/nullhack/agents-smith/network/members |
175 | | -[stars-shield]: https://img.shields.io/github/stars/nullhack/agents-smith.svg?style=for-the-badge |
176 | | -[stars-url]: https://github.com/nullhack/agents-smith/stargazers |
177 | | -[issues-shield]: https://img.shields.io/github/issues/nullhack/agents-smith.svg?style=for-the-badge |
178 | | -[issues-url]: https://github.com/nullhack/agents-smith/issues |
179 | | -[license-shield]: https://img.shields.io/badge/license-MIT-green?style=for-the-badge |
180 | | -[license-url]: https://github.com/nullhack/agents-smith/blob/main/LICENSE |
| 52 | +Only items listed in this section are deleted on purge. Edit this section to control what smith manages. |
0 commit comments