Skip to content

Commit 16215c2

Browse files
GitmaxdGitmaxd
committed
docs: Add idempotency, proof artifacts, references sections
- Added Idempotency section (safe to rerun) - Enhanced Success Criteria with artifact table - Added Proof Artifacts section for PRs - Added References section (AGENTS.md, mcp.json) - Added machine-parseable note to Artifacts
1 parent d4cd4be commit 16215c2

File tree

3 files changed

+137
-5
lines changed

3 files changed

+137
-5
lines changed

‎fix.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Surgical Enhancement Plan for droid-mode SKILL.md
2+
3+
## Change 1: Add Idempotency Statement
4+
**Location:** After "Key Insight" section
5+
**Add new section:**
6+
```markdown
7+
## Idempotency
8+
9+
All droid-mode commands are safe to rerun:
10+
- `dm servers` / `dm index` — read-only discovery
11+
- `dm hydrate` — overwrites previous hydration (timestamped)
12+
- `dm run` — each run creates a new timestamped trace
13+
14+
No cleanup required between invocations.
15+
```
16+
17+
---
18+
19+
## Change 2: Enhance Success Criteria with Concrete Artifacts
20+
**Location:** Replace existing "Success Criteria" section
21+
**Replace with:**
22+
```markdown
23+
## Success Criteria
24+
25+
The skill completes successfully when these artifacts exist:
26+
27+
| Artifact | Path | Content |
28+
|----------|------|---------|
29+
| Tool cache | `.factory/droid-mode/cache/<server>/tools.json` | Array of tool objects |
30+
| Hydrated schemas | `.factory/droid-mode/hydrated/<server>/<ts>/schemas.json` | Full JSON schemas |
31+
| TypeScript types | `.factory/droid-mode/hydrated/<server>/<ts>/types.d.ts` | Generated type definitions |
32+
| Execution trace | `.factory/droid-mode/runs/<server>/<ts>/run.json` | `{ error: false, result: ... }` |
33+
34+
Verify with: `dm doctor --server X` (should exit 0)
35+
```
36+
37+
---
38+
39+
## Change 3: Add Proof Artifacts Section
40+
**Location:** After "Verification" section
41+
**Add new section:**
42+
```markdown
43+
## Proof Artifacts
44+
45+
After completing a workflow, produce evidence:
46+
47+
- **Discovery proof**: Screenshot or paste of `dm index --server X` output
48+
- **Hydration proof**: Confirm `types.d.ts` exists and compiles (`tsc --noEmit`)
49+
- **Execution proof**: Link to `run.json` trace showing `error: false`
50+
- **For PRs**: Include trace file or summary in PR description
51+
```
52+
53+
---
54+
55+
## Change 4: Add Supporting References Section
56+
**Location:** After "Supporting Files" section
57+
**Add new section:**
58+
```markdown
59+
## References
60+
61+
For project-specific conventions, see:
62+
- `AGENTS.md` — project-wide agent guidance (if present)
63+
- `mcp.json` — MCP server configuration
64+
- `.factory/skills/*/SKILL.md` — related skills that may chain with droid-mode
65+
66+
For droid-mode internals:
67+
- `README.md` — full CLI documentation
68+
- `examples/` — sample workflows and hooks
69+
```
70+
71+
---
72+
73+
## Change 5: Add Machine-Parseable Output Note
74+
**Location:** In "Artifacts" section, add a note at the end
75+
**Append:**
76+
```markdown
77+
All JSON artifacts are machine-parseable for downstream skill chaining. Workflows can read `tools.json` or `run.json` to inform subsequent steps.
78+
```
79+
80+
---
81+
82+
## Summary of Changes
83+
84+
| Gap | Fix | Lines Added |
85+
|-----|-----|-------------|
86+
| Idempotency not stated | New "Idempotency" section | ~7 |
87+
| Success criteria vague | Replace with artifact table | ~12 |
88+
| No proof artifacts | New "Proof Artifacts" section | ~9 |
89+
| No references to AGENTS.md | New "References" section | ~10 |
90+
| Machine-parseable not noted | One-liner in Artifacts | ~2 |
91+
92+
**Total additions:** ~40 lines
93+
**No deletions** except replacing Success Criteria section (~5 lines)
94+
**Net change:** ~35 lines added
95+
96+
All changes preserve existing instructional content and command documentation.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "droid-mode",
3-
"version": "0.0.2",
3+
"version": "0.0.3",
44
"description": "Progressive Code-Mode MCP integration for Factory.ai Droid - access MCP tools without context bloat",
55
"type": "module",
66
"main": "dist/cli.js",

‎templates/skills/droid-mode/SKILL.md‎

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,15 @@ Servers with `disabled: true` in `mcp.json` are **fully available** to droid-mod
3535

3636
This is the entire point of the skill.
3737

38+
## Idempotency
39+
40+
All droid-mode commands are safe to rerun:
41+
- `dm servers` / `dm index` — read-only discovery
42+
- `dm hydrate` — overwrites previous hydration (timestamped)
43+
- `dm run` — each run creates a new timestamped trace
44+
45+
No cleanup required between invocations.
46+
3847
## Workflow Example
3948

4049
```js
@@ -57,13 +66,27 @@ After using droid-mode, verify:
5766
- [ ] Artifacts exist in `.factory/droid-mode/` (cache, hydrated, runs)
5867
- [ ] Workflow trace shows no errors (`runs/<server>/<ts>/run.json`)
5968

69+
## Proof Artifacts
70+
71+
After completing a workflow, produce evidence:
72+
73+
- **Discovery proof**: Screenshot or paste of `dm index --server X` output
74+
- **Hydration proof**: Confirm `types.d.ts` exists and compiles (`tsc --noEmit`)
75+
- **Execution proof**: Link to `run.json` trace showing `error: false`
76+
- **For PRs**: Include trace file or summary in PR description
77+
6078
## Success Criteria
6179

62-
The skill completes successfully when:
80+
The skill completes successfully when these artifacts exist:
6381

64-
- Tool discovery returned results (`dm index` shows tools)
65-
- Hydrated schemas are valid (`types.d.ts` generated)
66-
- Workflow executed without sandbox errors (trace shows `error: false`)
82+
| Artifact | Path | Content |
83+
|----------|------|---------|
84+
| Tool cache | `.factory/droid-mode/cache/<server>/tools.json` | Array of tool objects |
85+
| Hydrated schemas | `.factory/droid-mode/hydrated/<server>/<ts>/schemas.json` | Full JSON schemas |
86+
| TypeScript types | `.factory/droid-mode/hydrated/<server>/<ts>/types.d.ts` | Generated type definitions |
87+
| Execution trace | `.factory/droid-mode/runs/<server>/<ts>/run.json` | `{ error: false, result: ... }` |
88+
89+
Verify with: `dm doctor --server X` (should exit 0)
6790

6891
## Fallbacks
6992

@@ -88,10 +111,23 @@ All outputs written to `.factory/droid-mode/`:
88111
- `hydrated/<server>/<ts>/` — schemas + types
89112
- `runs/<server>/<ts>/run.json` — execution trace
90113

114+
All JSON artifacts are machine-parseable for downstream skill chaining. Workflows can read `tools.json` or `run.json` to inform subsequent steps.
115+
91116
## Supporting Files
92117

93118
- `bin/dm` — CLI entry point
94119
- `lib/` — implementation modules
95120
- `examples/workflows/` — sample workflow files
96121
- `examples/hooks/` — PreToolUse hook examples
97122
- `README.md` — full documentation
123+
124+
## References
125+
126+
For project-specific conventions, see:
127+
- `AGENTS.md` — project-wide agent guidance (if present)
128+
- `mcp.json` — MCP server configuration
129+
- `.factory/skills/*/SKILL.md` — related skills that may chain with droid-mode
130+
131+
For droid-mode internals:
132+
- `README.md` — full CLI documentation
133+
- `examples/` — sample workflows and hooks

0 commit comments

Comments
 (0)