You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Product requirements and goals: documentation/prd.rst
5
-
- System architecture and design: @documentation/architecture/
6
-
- Development practices and style: @.auxiliary/instructions/
7
-
- Current session notes and TODOs: @.auxiliary/notes/
3
+
- Overview and Quick Start: README.{md,rst}
4
+
- Architecture and Design: @documentation/architecture/
5
+
- Development Practices: @.auxiliary/instructions/
8
6
9
7
- Use the 'context7' MCP server to retrieve up-to-date documentation for any SDKs or APIs.
10
-
- Use the 'librovore' MCP server to search structured documentation sites with object inventories (Sphinx-based, compatible MkDocs with mkdocstrings). This bridges curated documentation (context7) and raw scraping (firecrawl).
8
+
- Use the 'nb' MCP server for project note-taking, issue tracking, and collaboration. The server provides LLM-friendly access to the `nb` note-taking system with proper escaping and project-specific notebook context.
11
9
- Check README files in directories you're working with for insights about architecture, constraints, and TODO items.
12
-
- Update files under `.auxiliary/notes` during conversation, removing completed tasks and adding emergent items.
13
10
14
-
<!-- OPENSPEC:START -->
15
-
# OpenSpec Instructions
11
+
## Purpose
16
12
17
-
These instructions are for AI assistants working in this project.
13
+
The project addresses the complete lifecycle of Python projects, from
14
+
creation to maintenance. It provides:
18
15
19
-
Always open `@/openspec/AGENTS.md` when the request:
20
-
- Mentions planning or proposals (words like proposal, spec, change, plan)
21
-
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
22
-
- Sounds ambiguous and you need the authoritative spec before coding
16
+
1. A Copier-based template for rapid scaffolding of new Python projects
17
+
with consistent structure and configuration.
18
+
2. A Python package (`emcdproj`) for ongoing project maintenance,
19
+
including static site generation and badge management.
20
+
3. A collection of reusable GitHub Actions workflows for CI/CD,
21
+
testing, and documentation.
23
22
24
-
Use `@/openspec/AGENTS.md` to learn:
25
-
- How to create and apply change proposals
26
-
- Spec format and conventions
27
-
- Project structure and guidelines
28
-
29
-
Keep this managed block so 'openspec update' can refresh the instructions.
@@ -44,26 +45,96 @@ Before implementing code changes, consult these files in `.auxiliary/instruction
44
45
45
46
- Use `rg --line-number --column` to get precise coordinates for MCP tools that require line/column positions.
46
47
- Choose appropriate editing tools based on the task complexity and your familiarity with the tools.
47
-
- Use the 'pyright' MCP server where appropriate:
48
-
-`rename_symbol` for refactors
49
-
-`references` for precise symbol analysis
50
-
- Use the 'rust-analyzer' MCP server where appropriate:
51
-
-`rename_symbol` for refactors
52
-
-`references` for precise symbol analysis
48
+
- Use a README-first discovery workflow to reduce token churn:
49
+
- Start at the repository root `README.{md,rst}`, then read the nearest relevant subtree README.
50
+
- After reading the nearest README, scope code searches to that subtree before considering repo-wide searches.
51
+
- If a touched subsystem README is stale after your change, update it in the same batch.
53
52
- Batch related changes together when possible to maintain consistency.
54
53
- Use relative paths rather than absolute paths when possible.
55
54
- Do not write to paths outside the current project unless explicitly requested.
56
-
- Use the `.auxiliary/scribbles` directory for scratch space instead of `/tmp`.
55
+
- Use `.auxiliary/scribbles` for scratch work and one-off experiments instead of `/tmp`; use `.auxiliary/temporary` for ephemeral test state and build artifacts that are safe to delete.
56
+
- In sandboxed environments (e.g., Codex CLI), treat file/network permission failures as escalation boundaries:
57
+
- If an operation fails due to sandbox, file access, or network restrictions, rerun it with user escalation.
58
+
- Do not spend time on retry loops or workaround exploration before escalating blocked operations.
59
+
60
+
## Note-Taking with `nb` MCP Server
61
+
62
+
### When to Use
63
+
-**Project coordination**: Record handoffs, document decisions, maintain task lists.
64
+
-**Issue tracking**: Create and manage todos with status tracking.
65
+
-**Knowledge sharing**: Document patterns, APIs, and project-specific knowledge.
66
+
-**Meeting notes**: Record discussions and action items.
67
+
68
+
### Scope and Noise Control
69
+
- Prefer to update an existing related note/todo over creating a new one when context already exists.
70
+
- Avoid logging routine, immediately completed mechanical actions in separate notes.
71
+
- Create new notes/todos when information is likely to be useful across sessions or for other collaborators.
- Prefer a folder taxonomy of `<issue-type>/<component>` (max depth 2) and avoid mixing top-level component folders with top-level issue-type folders.
89
+
- Recommended top-level issue types are:
90
+
-`todos/`
91
+
-`handoffs/`
92
+
-`coordination/`
93
+
-`decisions/` (optional for durable rationale notes)
94
+
- Example component names include `engine`, `mcp`, `tui`, `web`, `handbook`, and `data-models`.
95
+
- This project should define and document its specific component-folder conventions in the **Project Notes** section.
96
+
- For cross-component work, prefer `coordination/general` and use multiple `#component-*` tags.
97
+
- Keep notebook lifecycle hygiene:
98
+
- prune completed todos quickly,
99
+
- keep only active/near-term handoffs,
100
+
- delete stale history-only notes with no owner or action.
101
+
102
+
### `nb` vs OpenSpec Rubric
103
+
- Use **OpenSpec proposals** for cross-cutting changes, contract-shaping work, architecture shifts, or work that needs explicit design discussion.
104
+
- Use **`nb` todos/notes** for scoped, self-contained implementation tasks where the path is straightforward.
105
+
- For each active OpenSpec proposal, keep **exactly one** linked `nb` todo as the tracking anchor (with proposal reference), rather than duplicating full task trees in both systems.
106
+
- When in doubt, prefer OpenSpec first for design clarity, then track execution updates in the linked `nb` todo.
107
+
108
+
## Tests Development
109
+
110
+
- Prefer tests under `tests/unit` and `tests/integration` over inline `#[cfg(test)]` modules in `src/**`, unless there is a strong locality reason to keep tests adjacent to implementation.
111
+
- Prefer tests that exercise public interfaces; avoid source-inclusion patterns used only to reach private internals.
112
+
113
+
## OpenSpec Instructions
114
+
115
+
Workflow Guide: @openspec/AGENTS.md
116
+
117
+
Always open `openspec/AGENTS.md` when the request:
118
+
- Mentions planning or proposals (words like proposal, spec, change, plan).
119
+
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work.
120
+
- Sounds ambiguous and you need the authoritative spec before coding.
121
+
122
+
Use `openspec/AGENTS.md` to learn:
123
+
- How to create and apply change proposals
124
+
- Spec format and conventions
125
+
- Project structure and guidelines
57
126
58
127
# Commits
59
128
60
129
- Use `git status` to ensure all relevant changes are in the changeset.
61
130
- Do **not** commit without explicit user approval. Unless the user has requested the commit, **ask first** for a review of your work.
131
+
- Do **not** bypass commit safety checks (e.g., `--no-verify`, `--no-gpg-sign`) unless the user explicitly approves doing so.
62
132
- Use present tense, imperative mood verbs (e.g., "Fix" not "Fixed").
63
133
- Write sentences with proper punctuation.
64
134
- Include a `Co-Authored-By:` field as the final line. Should include the model name and a no-reply address.
135
+
- Avoid using `backticks` in commit messages as shell tools may evaluate them as subshell captures.
65
136
66
137
# Project Notes
67
138
68
139
<!-- This section accumulates project-specific knowledge, constraints, and deviations.
69
-
For structured items, use documentation/architecture/decisions/ and .auxiliary/notes/todo.md-->
140
+
For structured items, use documentation/architecture/decisions/ and `nb`.-->
0 commit comments