workspace-navigation

name	workspace-navigation
description	Navigate and organize shared agent workspaces with surgical efficiency. Use when working in collaborative repositories or coordinating across agents. Trigger phrases: 'organize this in the workspace', 'where does this belong in the structure', 'navigate to the relevant research', 'find the decision that answers this'.

OpenClaw Integration: This skill is invoked by the Dojo Genesis plugin via /dojo run workspace-navigation. The agent receives project context automatically via the before_agent_start hook. Use dojo_get_context for full state, dojo_save_artifact to persist outputs, and dojo_update_state to record phase transitions and decisions.

Agent Workspace Navigator Skill

Version: 1.0
Created: 2026-02-02
Author: Manus
Purpose: Efficiently navigate and interact with shared agent workspaces and discussion rooms

---

Overview

This skill encodes best practices for working in shared agent workspaces—structured repositories where multiple agents collaborate, think together, and build shared context. It provides patterns for reading, writing, and organizing content in a way that maximizes clarity, minimizes token waste, and enables effective collaboration.

Philosophy: A shared workspace is not a file dump—it's a thinking room. Structure enables clarity; clarity enables collaboration.

---

When to Use This Skill

• Working in a shared private repository with other agents
• Contributing to or reading from a collaborative discussion space
• Organizing thoughts, specifications, or research in a structured way
• Coordinating work across multiple agents or sessions
• Building shared context without unstructured file chaos

---

Workspace Structure

A well-structured agent workspace follows the Planning with Files philosophy and organizes content by purpose, not by time or author.

Standard Directory Structure

workspace/
├── README.md                    # Workspace overview and navigation guide
├── 00_Active/                   # Current work in progress
│   ├── discussions/             # Active discussions and threads
│   ├── drafts/                  # Work in progress (not final)
│   └── decisions/               # Decisions made (with rationale)
├── 01_Specifications/           # Finalized specs and designs
│   ├── architecture/            # System architecture docs
│   ├── features/                # Feature specifications
│   └── protocols/               # Protocols and standards
├── 02_Research/                 # Research findings and synthesis
│   ├── deep-dives/              # Deep research on specific topics
│   ├── landscape-scans/         # Wide research across domains
│   └── references/              # External sources and citations
├── 03_Memory/                   # Shared memory and knowledge base
│   ├── seeds/                   # Reusable patterns and insights
│   ├── learnings/               # Lessons learned
│   └── context/                 # Shared context for continuity
├── 04_Artifacts/                # Generated artifacts and outputs
│   ├── code/                    # Code examples or prototypes
│   ├── diagrams/                # Visual artifacts
│   └── documents/               # Final documents
└── 05_Archive/                  # Completed or deprecated work
    ├── by-date/                 # Time-based archive
    └── by-topic/                # Topic-based archive

File Naming Conventions

Format: YYYY-MM-DD_topic-name_author.md

Examples:

• 2026-02-02_memory-garden-design_manus.md
• 2026-02-02_context-compression-strategy_cipher.md
• 2026-02-02_collaboration-protocol_manus-cipher.md

Why:

• Date prefix enables chronological sorting
• Topic name provides context
• Author attribution enables tracking
• Underscore separators are filesystem-friendly

---

Reading from the Workspace

1. Start with the Index

Always read README.md first to understand:

• Workspace purpose and scope
• Directory structure and conventions
• Active discussions and priorities
• How to contribute

2. Navigate by Purpose, Not Time

Don't:

• Browse chronologically through all files
• Read everything in a directory

Do:

• Identify your purpose (e.g., "understand memory architecture")
• Navigate to the relevant directory (e.g., 01_Specifications/architecture/)
• Read the most recent or relevant file

3. Use Grep for Targeted Search

Pattern:

# Search for a specific topic across all markdown files
grep -r "memory compression" workspace/ --include="*.md"

# Search within a specific directory
grep -r "context window" workspace/01_Specifications/ --include="*.md"

# Search for discussions by a specific agent
grep -r "Author: Cipher" workspace/00_Active/discussions/ --include="*.md"

4. Read Metadata First

Every document should have frontmatter:

---
title: Memory Garden Design
author: Manus
date: 2026-02-02
status: Draft | Active | Final | Archived
tags: [memory, architecture, compression]
related: [context-compression-strategy, seed-extraction]
---

Read the metadata to decide:

• Is this relevant to my current task?
• Is this the most recent version?
• Who authored this, and should I coordinate with them?
• What related documents should I read?

5. Extract Key Insights Efficiently

Don't:

• Read every word of every document
• Copy entire documents into your context

Do:

• Skim for structure (headings, lists, tables)
• Extract key insights (1-3 sentences per section)
• Note open questions or decisions
• Link to the full document for reference

Template:

## Insights from [Document Title]

**Author:** [Name]  
**Date:** [YYYY-MM-DD]  
**Status:** [Draft/Active/Final]  
**Link:** [Path to document]

**Key Insights:**
- [Insight 1]
- [Insight 2]
- [Insight 3]

**Open Questions:**
- [Question 1]
- [Question 2]

**Decisions:**
- [Decision 1: Rationale]

**Relevance to Current Task:**
[How this informs what I'm working on]

---

Writing to the Workspace

1. Choose the Right Location

Ask:

• Is this work in progress or finalized?
• Is this a discussion, specification, or research?
• Who is the intended audience?

Decision Tree:

Is this finalized?
├─ No → 00_Active/
│   ├─ Is this a discussion? → discussions/
│   ├─ Is this a draft spec? → drafts/
│   └─ Is this a decision? → decisions/
└─ Yes → Where does it belong?
    ├─ Specification → 01_Specifications/
    ├─ Research → 02_Research/
    ├─ Knowledge/Pattern → 03_Memory/
    ├─ Artifact/Output → 04_Artifacts/
    └─ Completed/Deprecated → 05_Archive/

2. Use Structured Templates

Every document should follow a template to ensure consistency and clarity.

Discussion Template

---
title: [Discussion Topic]
author: [Your Name]
date: [YYYY-MM-DD]
status: Active
tags: [tag1, tag2, tag3]
participants: [agent1, agent2]
---

# [Discussion Topic]

## Context

[What is the background or situation that prompted this discussion?]

## Question / Problem

[What are we trying to decide or solve?]

## Perspectives

### Perspective 1: [Name]

[Description of this perspective]

**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]
- [Con 2]

### Perspective 2: [Name]

[Repeat structure]

## Open Questions

- [ ] [Question 1]
- [ ] [Question 2]

## Next Steps

- [ ] [Action 1: Owner]
- [ ] [Action 2: Owner]

## References

- [Link to related discussion]
- [Link to relevant spec]

Decision Template

---
title: [Decision Title]
author: [Your Name]
date: [YYYY-MM-DD]
status: Final
tags: [tag1, tag2, tag3]
decision_id: [Unique ID, e.g., DEC-001]
---

# Decision: [Title]

## Context

[What situation led to this decision?]

## Decision

[What was decided? Be specific and actionable.]

## Rationale

[Why was this decision made?]

**Factors Considered:**
- [Factor 1]
- [Factor 2]
- [Factor 3]

**Alternatives Considered:**
- [Alternative 1: Why rejected]
- [Alternative 2: Why rejected]

## Implications

**Immediate:**
- [Implication 1]
- [Implication 2]

**Long-term:**
- [Implication 1]
- [Implication 2]

## Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk 1] | Low/Med/High | Low/Med/High | [How to address] |

## Review Criteria

[How will we know if this decision was correct?]

- [ ] [Criterion 1]
- [ ] [Criterion 2]

## References

- [Link to discussion]
- [Link to research]

Specification Template

See specification-writer skill for full template.

Research Template

See research-modes skill for full template.

3. Write for Clarity and Scannability

Principles:

• Use headings to create structure
• Use lists for enumerations
• Use tables for comparisons
• Use blockquotes for key insights
• Use code blocks for examples

Don't:

• Write long paragraphs without structure
• Bury key insights in prose
• Use vague language ("maybe", "possibly", "might")

Do:

• Make headings descriptive ("Memory Compression Strategy" not "Strategy")
• Put key insights at the top (executive summary)
• Use specific language ("Use 3-month rule" not "Consider time-based compression")

4. Link to Related Content

Always include a "References" or "Related" section to help others navigate.

Format:

## Related Content

**Discussions:**
- [Discussion: Memory Architecture](../00_Active/discussions/2026-02-01_memory-architecture_manus.md)

**Specifications:**
- [Spec: Context Compression](../01_Specifications/architecture/context-compression.md)

**Research:**
- [Research: Semantic Compression Techniques](../02_Research/deep-dives/semantic-compression.md)

**Seeds:**
- [Seed: 3-Month Rule](../03_Memory/seeds/3-month-rule.md)

5. Update the Index

After creating or updating a document, update the workspace README.md to reflect:

• New active discussions
• Completed decisions
• Finalized specifications
• Key research findings

---

Collaboration Patterns

Pattern 1: Threaded Discussions

Use when: Multiple agents are exploring a topic together

Process:

1. Agent A creates initial discussion document in 00_Active/discussions/
2. Agent B reads and adds their perspective to the same document
3. Agent C reads both perspectives and synthesizes
4. When consensus is reached, move to 00_Active/decisions/

Template:

## Discussion Thread

### [Agent A] - [Date]

[Perspective or question]

### [Agent B] - [Date]

[Response or alternative perspective]

### [Agent C] - [Date]

[Synthesis or recommendation]

Pattern 2: Specification Review

Use when: One agent drafts a spec, another reviews

Process:

1. Agent A creates draft in 00_Active/drafts/
2. Agent A notifies Agent B (via discussion or shared log)
3. Agent B reviews and adds inline comments
4. Agent A addresses comments and updates draft
5. When finalized, move to 01_Specifications/

Comment Format:

<!-- COMMENT [Agent B]: This section needs more detail on error handling -->

Pattern 3: Parallel Research

Use when: Multiple agents research different aspects of the same problem

Process:

1. Agents agree on research scope and division of labor
2. Each agent creates their own research document in 02_Research/
3. Agents read each other's findings
4. One agent synthesizes into a unified document
5. Synthesized document is moved to 03_Memory/ as shared knowledge

Pattern 4: Seed Sharing

Use when: An agent extracts a reusable pattern

Process:

1. Agent extracts seed using seed-extraction skill
2. Agent documents seed in 03_Memory/seeds/
3. Agent updates seed index in 03_Memory/seeds/README.md
4. Other agents can discover and apply the seed

---

Token Efficiency Strategies

1. Surgical Reading

Don't:

• Read entire workspace into context
• Load all files in a directory

Do:

• Read README.md first (500-1000 tokens)
• Identify 2-3 relevant files (2000-5000 tokens each)
• Extract key insights into a summary (500-1000 tokens)
• Total: ~5,000-10,000 tokens vs. 50,000+ tokens

2. Incremental Context Building

Pattern:

1. Start with minimal context (README + current task)
2. Add context as needed (specific files)
3. Compress context after each major milestone
4. Archive completed work

3. Reference, Don't Copy

Don't:

• Copy entire documents into your working memory
• Duplicate content across multiple files

Do:

• Link to source documents
• Extract key insights (1-3 sentences)
• Reference by path and section

Example:

As documented in [Memory Architecture Spec](../01_Specifications/architecture/memory.md#compression-strategy), we use the 3-month rule for semantic compression.

4. Use Metadata for Filtering

Before reading a file, check metadata:

• Is this relevant? (tags, title)
• Is this current? (date, status)
• Is this authoritative? (author, decision_id)

This saves:

• Reading time (minutes)
• Token cost (thousands of tokens)
• Context pollution (irrelevant information)

---

Maintenance Practices

Weekly Review (30 minutes)

Tasks:

1. Review 00_Active/ directory
   • Move finalized drafts to appropriate directories
   • Archive completed discussions
   • Update decision log
2. Update workspace README.md
   • Reflect current priorities
   • Update navigation guide
3. Compress old discussions
   • Extract key insights into memory
   • Archive full discussions

Monthly Audit (1-2 hours)

Tasks:

1. Review 01_Specifications/ for outdated specs
2. Review 03_Memory/ for unused seeds
3. Archive deprecated content to 05_Archive/
4. Update directory structure if needed
5. Refactor for clarity and efficiency

---

Quality Checklist

Before committing content to the workspace, verify:

Structure

• File is in the correct directory
• File follows naming convention
• Metadata (frontmatter) is complete
• Headings create clear structure

Content

• Purpose is clear (why this document exists)
• Key insights are at the top
• Content is scannable (headings, lists, tables)
• Links to related content are included

Collaboration

• Author is identified
• Status is set (Draft/Active/Final/Archived)
• Tags enable discovery
• Workspace README is updated (if needed)

Token Efficiency

• Content is concise (no unnecessary prose)
• Structure enables surgical reading
• Metadata enables filtering
• References are used instead of duplication

---

Common Pitfalls to Avoid

❌ File Dumping: Creating files without structure → ✅ Use directory hierarchy
❌ Orphan Documents: No links to/from other content → ✅ Always link related content
❌ Stale Content: Old drafts never finalized or archived → ✅ Weekly review and cleanup
❌ Vague Naming: "thoughts.md", "notes.md" → ✅ Descriptive names with dates
❌ No Metadata: Can't filter or discover → ✅ Always include frontmatter

---

Usage Instructions

1. Read this skill before working in a shared workspace
2. Read the workspace README.md to understand structure and conventions
3. Navigate by purpose (use directory structure, not chronological browsing)
4. Use templates when creating new content
5. Link to related content to enable discovery
6. Update the index when adding significant content
7. Review and maintain regularly (weekly/monthly)

---

Skill Metadata

Token Savings: ~10,000-20,000 tokens per session (surgical reading, structured navigation, metadata filtering)
Quality Impact: Ensures workspace remains organized, discoverable, and collaborative
Maintenance: Update when workspace structure evolves

Related Skills:

• specification-writer - Use for writing specs in the workspace
• research-modes - Use for conducting research in the workspace
• seed-extraction - Use for extracting and documenting seeds
• memory-garden - Use for documenting memory entries

---

Last Updated: 2026-02-02
Maintained By: Manus
Status: Active

OpenClaw Tool Integration

When running inside the Dojo Genesis plugin:

1. Start by calling dojo_get_context to retrieve full project state, history, and artifacts
2. During the skill, follow the workflow steps documented above
3. Save outputs using dojo_save_artifact with the artifacts output directory
4. Update project state by calling dojo_update_state to record skill completion and any phase transitions