@joshski/dust 0.1.100 → 0.1.102

package/.dust/principles/actionable-errors.md

@@ -0,0 +1,18 @@
+# Actionable Errors
+
+Error messages should tell you what to do next, not just what went wrong.
+
+When something fails, the message should provide:
+- A clear description of the problem
+- Specific guidance on how to fix it
+- Context needed to take the next step
+
+This is especially important for AI agents, who need concrete instructions to recover autonomously. A good error message turns a dead end into a signpost.
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/agent-agnostic-design.md

@@ -0,0 +1,21 @@
+# Agent-Agnostic Design
+
+Dust should work with multiple agents without favoring one.
+
+Rather than implementing agents, Dust generates prompts and context that can be passed to any capable agent. This keeps Dust lightweight and allows teams to use whatever agent tooling they prefer.
+
+Dust may have built-in support for invoking popular agents (Claude, Aider, Codex, etc.), but the choice of agent should always be made by the user at runtime - never hard-coded into repository configuration.
+
+Note: Supporting multiple agents directly contributes to [Easy Adoption](easy-adoption.md), since teams can use their preferred agent tools without being locked into a specific platform.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/agent-autonomy.md

@@ -0,0 +1,19 @@
+# Agent Autonomy
+
+Dust exists to enable AI agents to produce work autonomously.
+
+With sufficient planning and small enough units, this works much better in practice.
+
+## Parent Principle
+
+- [Human-AI Collaboration](human-ai-collaboration.md)
+
+## Sub-Principles
+
+- [Actionable Errors](actionable-errors.md)
+- [Batteries Included](batteries-included.md)
+- [Agent-Agnostic Design](agent-agnostic-design.md)
+- [Agent Context Inference](agent-context-inference.md)
+- [Agent-Specific Enhancement](agent-specific-enhancement.md)
+- [Context Window Efficiency](context-window-efficiency.md)
+- [Small Units](small-units.md)

package/.dust/principles/agent-context-inference.md

@@ -0,0 +1,19 @@
+# Agent Context Inference
+
+Terse human prompts should trigger the correct agent action.
+
+When a human gives a brief instruction like "the button should be green", the agent should be able to infer what to do. The agent shouldn't require the human to specify file paths, component names, or implementation details that can be discovered from the repository.
+
+This reduces friction for humans and makes agent interactions feel more natural. The burden of context discovery shifts to the agent, which can use dust's CLI and repository structure to find what it needs.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/agent-specific-enhancement.md

@@ -0,0 +1,23 @@
+# Agent-Specific Enhancement
+
+Dust should detect and enhance the experience for specific agents while remaining agnostic at its core.
+
+While Dust has [Agent-Agnostic Design](agent-agnostic-design.md) and works with any capable agent, it can still optimize the "agent DX" (developer experience) when it detects a specific agent is being used. This means:
+
+- **Detection** - Dust may detect which agent is running (e.g., Claude Code, Aider, Cursor) through environment variables, configuration, or other signals
+- **Enhancement** - Once detected, Dust can tailor its output format, prompts, or context to leverage that agent's specific strengths
+- **Graceful fallback** - When no specific agent is detected, Dust provides a generic experience that works with any agent
+
+This principle complements Agent-Agnostic Design: the core functionality never requires a specific agent, but the experience improves when one is recognized.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/atomic-commits.md

@@ -0,0 +1,15 @@
+# Atomic Commits
+
+Each commit should tell a complete story, bundling implementation changes with their corresponding documentation updates.
+
+When a task is completed, the commit deletes the task file, updates relevant facts to reflect the new reality, and removes any ideas that have been realized. This discipline ensures that any point in the commit history represents a coherent, self-documenting state of the project.
+
+Clean commit history is essential because archaeology depends on it. Future humans and AI agents will traverse history to understand why decisions were made and how the system evolved.
+
+## Parent Principle
+
+- [Repository Hygiene](repository-hygiene.md)
+
+## Sub-Principles
+
+- [Traceable Decisions](traceable-decisions.md)

package/.dust/principles/batteries-included.md

@@ -0,0 +1,17 @@
+# Batteries Included
+
+Dust should provide everything that is required (within reason) for an agent to be productive in an arbitrary codebase.
+
+An agent working autonomously should not be blocked because a tool or configuration is missing. For example, dust should ship custom lint rules for different linters, even though those linters are not dependencies of dust itself. If an agent needs a capability to do its job well in a typical codebase, dust should provide it out of the box.
+
+This means accepting some breadth of scope — bundling configs, rules, and utilities that target external tools — in exchange for agents that can start producing useful work immediately without manual setup.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles

package/.dust/principles/boy-scout-rule.md

@@ -0,0 +1,15 @@
+# Boy Scout Rule
+
+Always leave the code better than you found it.
+
+When working in any area of the codebase, take the opportunity to make small improvements — clearer names, removed dead code, better structure — even if they're not directly related to the task at hand. These incremental improvements compound over time, preventing gradual decay and keeping the codebase healthy without requiring dedicated cleanup efforts.
+
+The Boy Scout Rule is not a license for large-scale refactoring during unrelated work. Improvements should be small, obvious, and low-risk. If a cleanup is too large to include alongside the current task, capture it as a separate task instead.
+
+## Parent Principle
+
+- [Maintainable Codebase](maintainable-codebase.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/broken-windows.md

@@ -0,0 +1,17 @@
+# Broken Windows
+
+Don't leave broken windows unrepaired.
+
+A broken window — a bad name, a hack, a TODO that lingers, a test that's been skipped — signals that nobody cares. That signal invites more neglect. One shortcut becomes two, then ten, and the codebase quietly rots from the inside.
+
+When you spot a broken window, fix it immediately if the fix is small. If it's too large, capture it as a task so it doesn't get forgotten. The key is to never normalise the damage. Even a comment acknowledging the problem ("this needs fixing because...") is better than silent acceptance.
+
+This principle complements the [Boy Scout Rule](boy-scout-rule.md): the Boy Scout Rule encourages proactive improvement, while Broken Windows warns against tolerating known problems. Together they keep entropy at bay.
+
+## Parent Principle
+
+- [Maintainable Codebase](maintainable-codebase.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/clarity-over-brevity.md

@@ -0,0 +1,13 @@
+# Clarity Over Brevity
+
+Names should be descriptive and self-documenting, even if longer.
+
+Abbreviated names like `ctx`, `deps`, `fs`, or `args` save a few keystrokes but obscure meaning. Full names like `context`, `dependencies`, `fileSystem`, and `arguments` make code immediately understandable without requiring readers to decode conventions. This is especially valuable when AI agents or new contributors read the codebase for the first time.
+
+## Parent Principle
+
+- [Naming Matters](naming-matters.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/co-located-tests.md

@@ -0,0 +1,13 @@
+# Co-located Tests
+
+Test files should live next to the code they test.
+
+When tests are co-located with their source files, developers can immediately see what's tested and what isn't. Finding the test for a module becomes trivial—it's right there in the same directory. This proximity encourages writing tests as part of the development flow rather than as an afterthought, and makes it natural to update tests when modifying code.
+
+## Parent Principle
+
+- [Intuitive Directory Structure](intuitive-directory-structure.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/comprehensive-assertions.md

@@ -0,0 +1,50 @@
+# Comprehensive Assertions
+
+Assert the whole, not the parts.
+
+When you break a complex object into many small assertions, a failure tells you *one thing that's wrong*. When you assert against the whole expected value, the diff tells you *what actually happened versus what you expected* — the full picture, in one glance.
+
+Small assertions are like yes/no questions to a witness. A whole-object assertion is like asking "tell me what you saw."
+
+## In practice
+
+Collapse multiple partial assertions into one comprehensive assertion:
+
+```javascript
+// Fragmented — each failure is a narrow keyhole
+expect(result.name).toBe("Alice");
+expect(result.age).toBe(30);
+expect(result.role).toBe("admin");
+
+// Whole — a failure diff tells the full story
+expect(result).toEqual({
+  name: "Alice",
+  age: 30,
+  role: "admin",
+});
+```
+
+If `role` is `"user"` and `age` is `29`, the fragmented version stops at the first failure. The whole-object assertion shows both discrepancies at once, in context.
+
+The same applies to arrays:
+
+```javascript
+// Avoid: partial assertions that hide the actual state
+expect(array).toContain('apples')
+expect(array).toContain('oranges')
+
+// Prefer: one assertion that reveals the full picture on failure
+expect(array).toEqual(['apples', 'oranges'])
+```
+
+## How to evaluate
+
+Work supports this principle when test failures tell a rich story — showing the complete actual value alongside the complete expected value, so the reader can understand what happened without re-running anything.
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/comprehensive-test-coverage.md

@@ -0,0 +1,15 @@
+# Comprehensive Test Coverage
+
+A project's test suite is its primary safety net, and agents depend on it even more than humans do.
+
+Agents cannot manually verify that their changes work. They rely entirely on automated tests to confirm correctness. Gaps in test coverage become gaps in agent capability — areas where changes are risky and feedback is absent. Comprehensive coverage means every meaningful behaviour is tested, so agents can make changes anywhere in the codebase with confidence.
+
+Dust should help projects measure and improve their test coverage, flag untested areas, and encourage a culture where new code comes with new tests.
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/consistent-naming.md

@@ -0,0 +1,13 @@
+# Consistent Naming
+
+Names should follow established conventions within each category to reduce cognitive load.
+
+Principles use Title Case. File names use kebab-case. Commands use lowercase with hyphens. When naming conventions exist, follow them. When they don't, establish one and apply it consistently. Inconsistent naming creates friction for both humans and AI agents trying to predict or recall identifiers.
+
+## Parent Principle
+
+- [Naming Matters](naming-matters.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/context-optimised-code.md

@@ -0,0 +1,15 @@
+# Context-Optimised Code
+
+Code should be structured so that agents can understand and modify it within their context window constraints.
+
+Large files, deeply nested abstractions, and sprawling dependency chains all work against agents. A 3,000-line file cannot be fully loaded into context. A function that requires understanding six levels of indirection demands more context than one that is self-contained. Context-optimised code favours small files, shallow abstractions, explicit dependencies, and co-located related logic.
+
+Dust should help projects identify files that are too large, modules that are too tangled, and patterns that make agent comprehension harder than it needs to be. This is not just about file size — it is about ensuring that the unit of code an agent needs to understand fits comfortably within the window available.
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/context-window-efficiency.md

@@ -0,0 +1,15 @@
+# Context Window Efficiency
+
+Dust should be designed with short attention spans in mind.
+
+AI agents operate within limited context windows. Every token consumed by planning artifacts is a token unavailable for reasoning about code. Dust keeps artifacts concise and scannable so agents can quickly understand what needs to be done without wading through verbose documentation.
+
+This means favoring brevity over completeness, using consistent structures that are fast to parse, and avoiding redundant information across files.
+
+## Parent Principle
+
+- [Agent Autonomy](agent-autonomy.md)
+
+## Sub-Principles
+
+- [Progressive Disclosure](progressive-disclosure.md)

package/.dust/principles/cross-platform-compatibility.md

@@ -0,0 +1,19 @@
+# Cross-Platform Compatibility
+
+Dust should work consistently across operating systems: Linux, macOS, and Windows.
+
+This means:
+- Avoiding platform-specific shell commands or syntax
+- Using cross-platform path handling
+- Testing on multiple platforms when possible
+- Documenting any platform-specific limitations
+
+Cross-platform support broadens adoption and ensures teams with mixed environments can collaborate effectively.
+
+## Parent Principle
+
+- [Easy Adoption](easy-adoption.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/debugging-tooling.md

@@ -0,0 +1,19 @@
+# Debugging Tooling
+
+Agents need effective tools for diagnosing and fixing issues without manual intervention.
+
+Traditional debugging relies on breakpoints, stepping through code, and interactive inspection — techniques that work well for humans but poorly for agents. Agents need debugging tools that produce readable, structured output: stack traces with context, diff-friendly error messages, reproducible test cases, and diagnostic commands that can be run non-interactively.
+
+Dust should help projects adopt agent-friendly debugging practices: structured error output, diagnostic scripts, snapshot testing for complex state, and tools that turn vague symptoms into specific, actionable information.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/decoupled-code.md

@@ -0,0 +1,16 @@
+# Decoupled Code
+
+Code should be organized into independent units with explicit dependencies.
+
+Decoupled code is easier to test, understand, and modify. Dependencies are passed in rather than hard-coded, enabling units to be tested in isolation and composed flexibly. This reduces the blast radius of changes and makes the system more maintainable.
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+- [Dependency Injection](dependency-injection.md)
+- [Stubs Over Mocks](stubs-over-mocks.md)
+- [Functional Core, Imperative Shell](functional-core-imperative-shell.md)
+- [Design for Testability](design-for-testability.md)

package/.dust/principles/dependency-injection.md

@@ -0,0 +1,15 @@
+# Dependency Injection
+
+Avoid global mocks. Dependency injection is almost always preferable to testing code that depends directly on globals.
+
+When code depends on global state or singletons, testing requires mocking those globals—which introduces hidden coupling, complicates test setup, and risks interference between tests. Dependency injection makes dependencies explicit: they're passed in as arguments, making the code's requirements visible and enabling tests to supply controlled implementations.
+
+This approach improves testability (each test controls its own dependencies), readability (dependencies are declared upfront), and flexibility (swapping implementations doesn't require changing the consuming code). It also makes refactoring safer since dependencies are explicit rather than implicit.
+
+## Parent Principle
+
+- [Decoupled Code](decoupled-code.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/design-for-testability.md

@@ -0,0 +1,17 @@
+# Design for Testability
+
+Design code to be testable first; good structure follows naturally.
+
+Testability should be a primary design driver, not a quality to be retrofitted. When code is designed to be testable from the start, it naturally becomes decoupled, explicit in its dependencies, and clear in its interfaces.
+
+The discipline of testability forces good design: functions become pure, dependencies become explicit, side effects become isolated. Rather than viewing testability as a tax on production code, recognize it as a compass that points toward better architecture.
+
+This is particularly important in agent-driven development. Agents cannot manually verify their changes—they rely entirely on tests. Code that resists testing resists autonomous modification.
+
+## Parent Principle
+
+- [Decoupled Code](decoupled-code.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/development-traceability.md

@@ -0,0 +1,19 @@
+# Development Traceability
+
+Structured logging and tracing help agents understand system behaviour without resorting to ad-hoc testing cycles.
+
+When something goes wrong, agents often resort to adding temporary log statements, running the code, reading the output, and repeating — a slow and wasteful debugging loop. Good traceability means the system already records what happened and why, through structured logs, trace IDs, and observable state. This lets agents diagnose issues by reading existing output rather than generating new experiments.
+
+Dust should encourage projects to adopt structured logging, promote traceability as a first-class concern, and provide tools that surface relevant trace information when agents need it.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/easy-adoption.md

@@ -0,0 +1,17 @@
+# Easy Adoption
+
+Dust should be trivially easy to adopt in any repository.
+
+Getting started with Dust should require minimal friction. A developer should be able to bootstrap Dust in their repository with a single command, without needing to install dependencies, configure build tools, or understand the internals.
+
+This lowers the barrier to entry and encourages experimentation.
+
+## Parent Principle
+
+- [Human-AI Collaboration](human-ai-collaboration.md)
+
+## Sub-Principles
+
+- [Cross-Platform Compatibility](cross-platform-compatibility.md)
+- [Unsurprising UX](unsurprising-ux.md)
+- [VCS Independence](vcs-independence.md)

package/.dust/principles/enable-flow-state.md

@@ -0,0 +1,20 @@
+# Enable Flow State
+
+Flow is the mental state where work becomes effortless - where you're fully immersed, losing track of time, operating at peak performance. Psychologist Mihaly Csikszentmihalyi identified three conditions that create flow: clear goals, immediate feedback, and challenge-skill balance.
+
+Dust's design targets these conditions directly:
+
+- **Clear goals**: Task files and lightweight planning give you a concrete target. You know exactly what you're building next.
+- **Immediate feedback**: Fast feedback loops let you see results quickly. Each change confirms you're on track or shows you what to adjust.
+- **Challenge-skill balance**: Small units of work and agent autonomy keep you in the zone - challenged enough to stay engaged, supported enough to succeed.
+
+Everything dust does serves flow. When developers stay in flow, they produce better work, sustain their energy, and enjoy the process.
+
+## Parent Principle
+
+- (none)
+
+## Sub-Principles
+
+- [Human-AI Collaboration](human-ai-collaboration.md)
+- [Maintainable Codebase](maintainable-codebase.md)

package/.dust/principles/environment-independent-tests.md

@@ -0,0 +1,19 @@
+# Environment-Independent Tests
+
+Tests must produce the same result regardless of where they run. A test that passes locally but fails in CI (or vice versa) is a broken test.
+
+Concretely, tests should never depend on:
+- Ambient environment variables (e.g. `CLAUDECODE`, `CI`, `HOME`)
+- The current working directory or filesystem layout of the host machine
+- Network availability or external services
+- The identity of the user or agent running the tests
+
+When a function's behavior depends on environment variables, the test must explicitly control those variables (via `stubEnv`, dependency injection, or passing an `env` parameter) rather than relying on whatever happens to be set in the current shell.
+
+## Parent Principle
+
+- [Test Isolation](test-isolation.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/exploratory-tooling.md

@@ -0,0 +1,19 @@
+# Exploratory Tooling
+
+Agents need tools to efficiently explore and understand unfamiliar codebases.
+
+When an agent encounters a new codebase — or an unfamiliar corner of a familiar one — it needs to quickly build a mental model: what exists, how it fits together, and where to make changes. Without good exploratory tools, agents waste context on trial-and-error searches, reading irrelevant files, and forming incorrect assumptions.
+
+Dust should promote and integrate tools that help agents explore: dependency graphs, module overviews, search utilities tuned for code navigation, and summaries of project structure. The goal is to make the "orientation" phase of any task as short and reliable as possible.
+
+## Applicability
+
+Internal
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/fast-feedback-loops.md

@@ -0,0 +1,15 @@
+# Fast Feedback Loops
+
+The primary feedback loop — write code, run checks, see results — should be as fast as possible.
+
+Fast feedback is the foundation of productive development, for both humans and agents. When tests, linters, and type checks run in seconds rather than minutes, developers iterate more frequently and catch problems earlier. Agents especially benefit because they operate in tight loops of change-and-verify; slow feedback wastes tokens and context window space on waiting rather than working.
+
+Dust should help projects measure the speed of their feedback loops, identify bottlenecks, and keep them fast as the codebase grows. This includes promoting practices like unit tests over integration tests for speed, incremental compilation, and check parallelisation.
+
+## Parent Principle
+
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/fast-feedback.md

@@ -0,0 +1,13 @@
+# Fast Feedback
+
+Dust should provide fast feedback loops for developers.
+
+Scripts and tooling should execute quickly so developers can iterate rapidly. Slow feedback discourages frequent validation and leads to larger, riskier changes. Fast feedback enables small, confident steps.
+
+## Parent Principle
+
+- [Make Changes with Confidence](make-changes-with-confidence.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/functional-core-imperative-shell.md

@@ -0,0 +1,15 @@
+# Functional Core, Imperative Shell
+
+Separate code into a pure "functional core" and a thin "imperative shell." The core takes values in and returns values out, with no side effects. The shell handles I/O and wires things together.
+
+Purely functional code makes some things easier to understand: because values don't change, you can call functions and know that only their return value matters—they don't change anything outside themselves.
+
+The functional core contains business logic as pure functions that take values and return values. The imperative shell sits at the boundary, reading input, calling into the core, and performing side effects with the results. This keeps the majority of code easy to test (no mocks or stubs needed for pure functions) and makes the I/O surface area small and explicit.
+
+## Parent Principle
+
+- [Decoupled Code](decoupled-code.md)
+
+## Sub-Principles
+
+- (none)

package/.dust/principles/human-ai-collaboration.md

@@ -0,0 +1,18 @@
+# Human-AI Collaboration
+
+Dust exists to enable effective collaboration between humans and AI agents on complex projects.
+
+The human is the CEO — they set direction, make strategic decisions, and check in when it matters. Dust is the PM — it manages the work, prepares context, and brings fully-researched questions to the human rather than expecting them to drive every detail. Agents are the developers — they read code, write changes, and iterate autonomously.
+
+Today's AI coding tools keep humans in a tight loop with agents. Dust is designed to loosen that loop, so humans spend less time directing and more time deciding.
+
+## Parent Principle
+
+- [Enable Flow State](enable-flow-state.md)
+
+## Sub-Principles
+
+- [Agent Autonomy](agent-autonomy.md)
+- [Easy Adoption](easy-adoption.md)
+- [Ideal Agent Developer Experience](ideal-agent-developer-experience.md)
+- [Lightweight Planning](lightweight-planning.md)

package/.dust/principles/ideal-agent-developer-experience.md

@@ -0,0 +1,24 @@
+# Ideal Agent Developer Experience
+
+The agent is the developer. The human is the CEO. Dust is the PM.
+
+With today's AI coding assistants, the human is stuck in a tight loop with agents — constantly directing, reviewing, and course-correcting. Dust is designed to relieve humans from this tight loop. Like an assistant to a CEO, dust predominantly brings fully-researched questions and well-prepared work to the human, rather than expecting the human to drive every decision. The human checks in less frequently, and when they do, they make high-leverage strategic calls rather than micromanaging implementation.
+
+For this to work, the agent's development environment must be excellent. The agent reads the code, writes changes, runs the checks, and iterates until the task is done. Everything about the codebase and its tooling either helps or hinders that process. Comprehensive tests are the agent's only way to verify correctness. Fast feedback loops are the agent's iteration speed. Structured logs are the agent's eyes into runtime behaviour. Small, well-organised files are what fit in the agent's context window. Exploratory and debugging tools are how the agent navigates and diagnoses without trial and error.
+
+Each sub-principle represents a different aspect of the ideal agent developer setup. The better these are, the less the human needs to be in the loop.
+
+## Parent Principle
+
+- [Human-AI Collaboration](human-ai-collaboration.md)
+
+## Sub-Principles
+
+- [Comprehensive Test Coverage](comprehensive-test-coverage.md)
+- [Fast Feedback Loops](fast-feedback-loops.md)
+- [Slow Feedback Coping](slow-feedback-coping.md)
+- [Development Traceability](development-traceability.md)
+- [Context-Optimised Code](context-optimised-code.md)
+- [Exploratory Tooling](exploratory-tooling.md)
+- [Debugging Tooling](debugging-tooling.md)
+- [Self-Contained Repository](self-contained-repository.md)

package/.dust/principles/intuitive-directory-structure.md

@@ -0,0 +1,13 @@
+# Intuitive Directory Structure
+
+Code should be organized around related concerns in clearly named directories.
+
+When files that serve similar purposes are grouped together, the codebase becomes easier to navigate and understand. A developer looking for "commands" should find them in a `commands` directory. Utilities should live with utilities. This organization reduces cognitive load and makes the project structure self-documenting.
+
+## Parent Principle
+
+- [Maintainable Codebase](maintainable-codebase.md)
+
+## Sub-Principles
+
+- [Co-located Tests](co-located-tests.md)