scriptoriumadmin/smriti
1
0
Fork 0
mirror of https://github.com/himanshudongre/smriti.git synced 2026-08-28 05:14:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update skill pack for attached repo workflow

Browse source
This commit is contained in:
Himanshu Dongre 2026-05-19 00:01:40 +05:30
parent b3734f3dc3
commit 0c8f6922f4
3 changed files with 78 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
AGENTS.md
View file

@ -1,5 +1,5 @@
---
smriti_skill_pack_version: 2.3
smriti_skill_pack_version: 2.4
title: Smriti — how to use it well
target: Codex
---
@ -51,13 +51,20 @@ At the start of every session where you are working on a Smriti-enabled
project, your FIRST action is:
```
smriti state <project>
smriti state
```
Before you read any file. Before you run any test. Before you plan
anything. Before you answer the user's first prompt beyond "let me
check the state first."
CLI workflow: bind the repo once
with `smriti init <space>` or `smriti attach <space>`. That writes
`.smriti.json` at the repo root. After that, everyday commands run from
anywhere inside the attached repo resolve the space automatically. If a repo is
not attached yet, attach it first or pass the explicit `<space>` argument for
that one command.
The state brief is the minimum context you need to continue work
without re-discovering decisions that were already made. Calling it
unconditionally is cheap, and missing it is expensive. The brief is
@ -67,7 +74,7 @@ section with an author tag, and if any of them disagree with main on
decisions you will see a `## Divergence signal` section.
For session start, prefer `--compact` mode:
`smriti state <project> --compact`
`smriti state --compact`
This omits artifact content to save tokens — artifact labels and a
recovery command are still shown. If the state brief lists artifacts
relevant to your task, retrieve them with
@ -277,7 +284,7 @@ agents can see what you are about to do.
**When to create a claim:**
```
smriti claim create <project> --agent <your-agent> --scope "<one sentence>" --intent-type implement
smriti claim create --agent <your-agent> --scope "<one sentence>" --intent-type implement
```
Create the claim after you know what you are going to work on but
@ -339,7 +346,7 @@ The reflex: when you start substantial work on a project where another
agent might be active, open a worktree before your first edit.
```
smriti worktree open <project> --agent <your-id>
smriti worktree open --agent <your-id>
```
This returns a path. Use that path as your working directory for the
@ -350,7 +357,7 @@ filesystem state is invisible to you and yours to them.
When you create your work claim, bind it to the worktree:
```
smriti claim create <project> --agent <your-id> \
smriti claim create --agent <your-id> \
--scope "..." --intent-type implement \
--task-id <task-id> --worktree <worktree-id>
```
@ -423,7 +430,7 @@ The default branch name when you `smriti worktree open` is
PR titles. Pass `--branch <name>` to use a custom branch name instead:
```
smriti worktree open <space> --agent <id> --branch v3-feature-name
smriti worktree open --agent <id> --branch v3-feature-name
```
Use this when the worktree maps cleanly to a single feature/PR. Stick
@ -436,7 +443,7 @@ If you have been working for more than a few minutes, check whether
the project state has moved since you started — before you checkpoint.
```
smriti state <project> --since <your-base-checkpoint-id> --compact
smriti state --since <your-base-checkpoint-id> --compact
```
Your base checkpoint ID is the HEAD you read at session start, or the
@ -494,14 +501,14 @@ Each task can have:
**Claim with task ID when available.** When you create a claim for a
task that has an ID, reference it:
`smriti claim create <project> --agent <your-agent> --scope "..." --task-id arch-docs --intent-type docs`
`smriti claim create --agent <your-agent> --scope "..." --task-id arch-docs --intent-type docs`
This makes your claim precisely traceable to a task, not just loosely
matched by scope text.
**Recheck after claiming.** If another agent might be starting at the
same time (e.g., you were both launched together), re-read the state
briefly after creating your claim:
`smriti state <project> --compact`
`smriti state --compact`
Check `## Active work` for duplicate `task:` references. If another
agent claimed the same task ID, abandon your claim and pick a
different task. This catches near-simultaneous collisions within
@ -557,7 +564,7 @@ assumptions, tasks, open questions, entities, artifacts) for you.
Example call:
```
cat <<'MD' | smriti checkpoint create <project> --extract --author-agent <your-agent-name>
cat <<'MD' | smriti checkpoint create --extract --author-agent <your-agent-name>
# Decided on Pydantic for the state validation layer
After trying dataclass-based validation and hitting the injection
@ -717,7 +724,7 @@ smriti fork <current-head-id> --branch alternative-X
Then write a checkpoint into the forked session:
```
cat fork.md | smriti checkpoint create <project> \
cat fork.md | smriti checkpoint create \
--extract --session <fork-session-id> --author-agent <your-agent-name>
```
@ -964,7 +971,7 @@ tell you. Do not guess.
---
*Smriti skill pack version cli-2.2 — this file is
*Smriti skill pack version cli-2.4 — this file is
authoritative for agent behaviour on this project. If you catch it
contradicting itself or your observed behaviour of the tools, tell
the human; the skill pack is versioned and meant to be updated.*

36
cli/smriti_cli/skill_pack/template.md
View file

@ -1,5 +1,5 @@
---
smriti_skill_pack_version: 2.3
smriti_skill_pack_version: 2.4
title: Smriti — how to use it well
target: {{display_name}}
---
@ -51,13 +51,23 @@ At the start of every session where you are working on a Smriti-enabled
project, your FIRST action is:
```
{{mcp:smriti_state(space="<project>")}}{{cli:smriti state <project>}}
{{mcp:smriti_state(space="<project>")}}{{cli:smriti state}}
```
Before you read any file. Before you run any test. Before you plan
anything. Before you answer the user's first prompt beyond "let me
check the state first."
{{mcp:When using MCP tools directly, keep passing `space="<project>"`.
The MCP server may run from the host's arbitrary working directory, so
it cannot rely on the repo-local `.smriti.json` attachment unless the
host passes a project path separately.}}{{cli:CLI workflow: bind the repo once
with `smriti init <space>` or `smriti attach <space>`. That writes
`.smriti.json` at the repo root. After that, everyday commands run from
anywhere inside the attached repo resolve the space automatically. If a repo is
not attached yet, attach it first or pass the explicit `<space>` argument for
that one command.}}
The state brief is the minimum context you need to continue work
without re-discovering decisions that were already made. Calling it
unconditionally is cheap, and missing it is expensive. The brief is
@ -67,7 +77,7 @@ section with an author tag, and if any of them disagree with main on
decisions you will see a `## Divergence signal` section.
For session start, prefer `--compact` mode:
{{mcp:`smriti_state(space="<project>", compact=True)`}}{{cli:`smriti state <project> --compact`}}
{{mcp:`smriti_state(space="<project>", compact=True)`}}{{cli:`smriti state --compact`}}
This omits artifact content to save tokens — artifact labels and a
recovery command are still shown. If the state brief lists artifacts
relevant to your task, retrieve them with
@ -277,7 +287,7 @@ agents can see what you are about to do.
**When to create a claim:**
```
{{mcp:smriti_claim(space="<project>", scope="<one sentence>", agent="<your-agent>", intent_type="implement")}}{{cli:smriti claim create <project> --agent <your-agent> --scope "<one sentence>" --intent-type implement}}
{{mcp:smriti_claim(space="<project>", scope="<one sentence>", agent="<your-agent>", intent_type="implement")}}{{cli:smriti claim create --agent <your-agent> --scope "<one sentence>" --intent-type implement}}
```
Create the claim after you know what you are going to work on but
@ -339,7 +349,7 @@ The reflex: when you start substantial work on a project where another
agent might be active, open a worktree before your first edit.
```
{{mcp:smriti_worktree_open(space="<project>", agent="<your-id>")}}{{cli:smriti worktree open <project> --agent <your-id>}}
{{mcp:smriti_worktree_open(space="<project>", agent="<your-id>")}}{{cli:smriti worktree open --agent <your-id>}}
```
This returns a path. Use that path as your working directory for the
@ -350,7 +360,7 @@ filesystem state is invisible to you and yours to them.
When you create your work claim, bind it to the worktree:
```
{{mcp:smriti_claim(space="<project>", scope="...", agent="<your-id>", intent_type="implement", task_id="<task-id>", worktree_id="<worktree-id>")}}{{cli:smriti claim create <project> --agent <your-id> \
{{mcp:smriti_claim(space="<project>", scope="...", agent="<your-id>", intent_type="implement", task_id="<task-id>", worktree_id="<worktree-id>")}}{{cli:smriti claim create --agent <your-id> \
--scope "..." --intent-type implement \
--task-id <task-id> --worktree <worktree-id>}}
```
@ -423,7 +433,7 @@ The default branch name when you `smriti worktree open` is
PR titles. Pass `--branch <name>` to use a custom branch name instead:
```
smriti worktree open <space> --agent <id> --branch v3-feature-name
smriti worktree open --agent <id> --branch v3-feature-name
```
Use this when the worktree maps cleanly to a single feature/PR. Stick
@ -436,7 +446,7 @@ If you have been working for more than a few minutes, check whether
the project state has moved since you started — before you checkpoint.
```
{{mcp:smriti_state(space="<project>", since="<your-base-checkpoint-id>", compact=True)}}{{cli:smriti state <project> --since <your-base-checkpoint-id> --compact}}
{{mcp:smriti_state(space="<project>", since="<your-base-checkpoint-id>", compact=True)}}{{cli:smriti state --since <your-base-checkpoint-id> --compact}}
```
Your base checkpoint ID is the HEAD you read at session start, or the
@ -494,14 +504,14 @@ Each task can have:
**Claim with task ID when available.** When you create a claim for a
task that has an ID, reference it:
{{mcp:`smriti_claim(space="<project>", scope="...", task_id="arch-docs", intent_type="docs")`}}{{cli:`smriti claim create <project> --agent <your-agent> --scope "..." --task-id arch-docs --intent-type docs`}}
{{mcp:`smriti_claim(space="<project>", scope="...", task_id="arch-docs", intent_type="docs")`}}{{cli:`smriti claim create --agent <your-agent> --scope "..." --task-id arch-docs --intent-type docs`}}
This makes your claim precisely traceable to a task, not just loosely
matched by scope text.
**Recheck after claiming.** If another agent might be starting at the
same time (e.g., you were both launched together), re-read the state
briefly after creating your claim:
{{mcp:`smriti_state(space="<project>", compact=True)`}}{{cli:`smriti state <project> --compact`}}
{{mcp:`smriti_state(space="<project>", compact=True)`}}{{cli:`smriti state --compact`}}
Check `## Active work` for duplicate `task:` references. If another
agent claimed the same task ID, abandon your claim and pick a
different task. This catches near-simultaneous collisions within
@ -573,7 +583,7 @@ and `extra="forbid"`. Latency overhead is ~0.3 ms per call.
author_agent="claude-code",
)
```}}{{cli:```
cat <<'MD' | smriti checkpoint create <project> --extract --author-agent <your-agent-name>
cat <<'MD' | smriti checkpoint create --extract --author-agent <your-agent-name>
# Decided on Pydantic for the state validation layer
After trying dataclass-based validation and hitting the injection
@ -739,7 +749,7 @@ smriti_create_checkpoint(
content="...",
)
```}}{{cli:```
cat fork.md | smriti checkpoint create <project> \
cat fork.md | smriti checkpoint create \
--extract --session <fork-session-id> --author-agent <your-agent-name>
```}}
@ -988,7 +998,7 @@ tell you. Do not guess.
---
*Smriti skill pack version {{primary_mode}}-2.2 — this file is
*Smriti skill pack version {{primary_mode}}-2.4 — this file is
authoritative for agent behaviour on this project. If you catch it
contradicting itself or your observed behaviour of the tools, tell
the human; the skill pack is versioned and meant to be updated.*

36
cli/tests/test_skill_pack.py
View file

@ -43,7 +43,7 @@ def test_load_template_nonempty():
def test_get_version_parses_frontmatter():
version = get_version()
assert version == "2.3"
assert version == "2.4"
def test_get_version_raises_when_frontmatter_missing():
@ -118,6 +118,7 @@ _REQUIRED_PHRASES = [
"20 checkpoints is producing noise",
# Section 3 — the reflex
"Reading current state from Smriti",
".smriti.json",
# Section 11 — anti-patterns
"HANDOFF.md",
"author_agent",
@ -208,6 +209,39 @@ def test_render_contains_all_critical_content(target_key: str):
)
def test_codex_render_teaches_attached_repo_no_arg_workflow():
"""Codex's CLI-native guide should prefer repo-attached no-arg commands."""
out = render("codex")
for phrase in [
"attached repo",
"smriti init <space>",
"smriti attach <space>",
"smriti state",
"smriti state --compact",
"smriti claim create --agent",
"smriti checkpoint create --extract",
]:
assert phrase in out
for stale_example in [
"smriti state <project>",
"smriti state <project> --compact",
"smriti claim create <project>",
"smriti checkpoint create <project>",
]:
assert stale_example not in out
def test_claude_render_keeps_explicit_space_for_mcp_tools():
"""MCP guidance still needs explicit space args instead of repo CWD binding."""
out = render("claude-code")
assert "space=\"<project>\"" in out
assert "repo-local `.smriti.json` attachment" in out
assert "smriti_state(space=\"<project>\")" in out
def test_render_targets_share_anti_pattern_section():
"""Both targets should include the same When-NOT-to-checkpoint
bullet structure. String-match the most distinctive phrases that