laantungir/ngit-grasp

Fork 0

mirror of https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git synced 2026-10-05 15:08:24 +00:00

Files

T

DanConwayDev 52bad9954c docs: use Diátaxis structure

2025-11-04 10:25:53 +00:00

21 KiB

Raw Blame History

AI Agent Guidelines for ngit-grasp

Purpose: Ensure AI agents (and humans) maintain consistent documentation practices and avoid common pitfalls.

Last Updated: November 4, 2025

📁 Documentation Structure

Overview

We use the Diátaxis framework for all documentation. This prevents documentation sprawl by organizing content into four clear categories based on purpose and audience.

ngit-grasp/
├── README.md                    # Project overview (keep updated)
├── AGENTS.md                    # This file - agent guidelines
├── CHANGELOG.md                 # User-facing changes (semver)
│
├── work/                        # Temporary session files (.gitignore'd)
│   ├── README.md               # Only file committed to git
│   └── *.md                    # Session notes, status, plans (temporary)
│
├── docs/                        # All documentation (Diátaxis structure)
│   ├── README.md               # Navigation guide with quadrant diagram
│   │
│   ├── tutorials/              # Learning-oriented (practical + learning)
│   │   ├── getting-started.md  # First-time setup
│   │   └── first-audit.md      # Running your first audit
│   │
│   ├── how-to/                 # Task-oriented (practical + working)
│   │   ├── deploy.md           # Production deployment
│   │   ├── nix-flakes.md       # Nix environment setup
│   │   ├── test-compliance.md  # Running compliance tests
│   │   └── upgrade-nostr-sdk.md # SDK upgrade guide
│   │
│   ├── reference/              # Information-oriented (theoretical + working)
│   │   ├── git-protocol.md     # Git Smart HTTP protocol
│   │   ├── grasp-protocol.md   # GRASP specification
│   │   ├── configuration.md    # All config options
│   │   ├── test-strategy.md    # Testing reference
│   │   └── api.md              # Internal API docs
│   │
│   ├── explanation/            # Understanding-oriented (theoretical + learning)
│   │   ├── architecture.md     # System design overview
│   │   ├── inline-authorization.md # Why inline auth?
│   │   ├── comparison.md       # vs ngit-relay
│   │   └── decisions.md        # Design decisions
│   │
│   ├── archive/                # Historical session notes
│   │   └── YYYY-MM-DD-*.md     # Completed work
│   │
│   └── learnings/              # DEPRECATED - migrated to Diátaxis
│       └── README.md           # Migration notice
│
├── grasp-audit/                # Audit tool subproject
│   ├── README.md              # Main audit docs
│   └── docs/                  # Follows same Diátaxis structure
│       ├── tutorials/
│       ├── how-to/
│       ├── reference/
│       └── explanation/
│
└── .ai/                        # AI assistant context (ignored in git)
    └── history/               # Conversation history

Diátaxis Framework

All documentation MUST fit into one of four categories:

📚 Tutorials (docs/tutorials/)

Purpose: Learning-oriented, teach by doing
Audience: Newcomers, beginners
Style: Step-by-step lessons with guaranteed outcomes
Examples: Getting Started, First Audit
Question: "Can you teach me to...?"

🔧 How-To Guides (docs/how-to/)

Purpose: Task-oriented, solve problems
Audience: Users with basic knowledge
Style: Practical recipes and solutions
Examples: Deploy, Configure, Troubleshoot
Question: "How do I...?"

📖 Reference (docs/reference/)

Purpose: Information-oriented, technical facts
Audience: Users looking up specific information
Style: Dry, factual, comprehensive
Examples: API docs, Config options, Protocols
Question: "What is...?"

💡 Explanation (docs/explanation/)

Purpose: Understanding-oriented, clarify concepts
Audience: Users wanting deeper understanding
Style: Discussion, context, alternatives
Examples: Architecture, Design Decisions, Comparisons
Question: "Why...?"

See: Diátaxis documentation for detailed guidance.

File Type Guidelines

Markdown (.md):

Primary format for all documentation
Easy to read in plain text and rendered
Supports code blocks, links, tables
Version control friendly

Text (.txt):

Only for visual ASCII art summaries
Must be archived after session (never permanent)
Examples: status boxes, visual diagrams
Archive to docs/archive/YYYY-MM-DD-name.txt

Other formats:

Avoid unless absolutely necessary
If needed, document in README.md why

📋 Document Lifecycle

1. Working Documents (work/ Directory)

Purpose: Session-specific temporary files
Location: work/ directory (.gitignore'd)
Lifecycle: Created → Used → Archived or Deleted
Retention: Archive valuable content, delete rest at session end

Examples:

work/session-notes.md → Session notes and progress
work/status.md → Current status report
work/migration-plan.md → Planning document
work/visual-summary.txt → ASCII art summaries

Rules:

✅ Create ALL session-specific docs in work/
✅ Use descriptive names (no date prefix needed)
✅ Archive valuable content to docs/archive/YYYY-MM-DD-name.md
✅ Delete obsolete files at session end
✅ Keep work/ clean (empty except README.md when not in session)
❌ Don't commit work/ contents to git (except README.md)
❌ Don't reference work/ docs from permanent documentation
❌ Don't let work/ accumulate files between sessions

Why work/ instead of root:

Keeps root clean (only README.md, AGENTS.md, CHANGELOG.md)
Clear separation: permanent vs. temporary
Not committed to git (reduces noise)
Easy to clean up (just rm -rf work/*)

2. Permanent Documentation (docs/)

Purpose: Long-term reference, architecture, guides
Location: docs/ (organized by Diátaxis category)
Lifecycle: Created → Maintained → Updated
Retention: Permanent (version controlled)

Structure:

docs/tutorials/ - Learning-oriented lessons
docs/how-to/ - Task-oriented guides
docs/reference/ - Information-oriented facts
docs/explanation/ - Understanding-oriented discussion

Examples:

docs/tutorials/getting-started.md - First-time setup
docs/how-to/deploy.md - Deployment guide
docs/reference/configuration.md - Config options
docs/explanation/architecture.md - System design

Rules:

✅ Categorize by Diátaxis framework (tutorial/how-to/reference/explanation)
✅ Keep updated as project evolves
✅ Use clear structure and headings
✅ Link between related docs
❌ Don't duplicate information (use links)
❌ Don't include session-specific details
❌ Don't put docs in wrong category (see Diátaxis guide)

3. Archive (docs/archive/)

Purpose: Historical record, completed phases
Location: docs/archive/
Lifecycle: Moved from root → Archived
Retention: Permanent (for reference)

Examples:

docs/archive/2025-11-04-tag-migration.md
docs/archive/2025-11-03-architecture-investigation.md

Rules:

✅ Rename with date prefix when archiving
✅ Add "ARCHIVED" marker at top
✅ Extract learnings to docs/learnings/ first
❌ Don't modify after archiving
❌ Don't reference in active documentation

4. Learnings (DEPRECATED)

Status: docs/learnings/ is deprecated - content migrated to Diátaxis structure

Migration:

Gotchas and patterns → docs/how-to/
Technical details → docs/reference/
Understanding concepts → docs/explanation/

Examples:

learnings/nix-flakes.md → how-to/nix-flakes.md
learnings/nostr-sdk.md → reference/nostr-sdk-upgrade.md
learnings/git-http-backend.md → reference/git-protocol.md

Rules:

❌ Don't create new files in docs/learnings/
✅ Migrate existing content to appropriate Diátaxis category
✅ Add redirect notice in old location

🔄 Cleanup Process

When to Clean Up

Trigger: End of session OR work/ has >5 files
Frequency: End of each session (mandatory)
Responsibility: AI agents should proactively clean up before session end

Cleanup Steps

Review work/ Directory
```
# List all working docs
ls -la work/
```
Extract to Diátaxis Categories
- Review each doc in work/
- Extract valuable content to appropriate category:
  - Gotchas/solutions → docs/how-to/
  - Technical facts → docs/reference/
  - Concepts/design → docs/explanation/
  - Lessons → docs/tutorials/

Archive Important Session Docs

# Archive valuable session docs with date prefix
mv work/migration-complete.md docs/archive/2025-11-04-migration-complete.md
mv work/visual-summary.txt docs/archive/2025-11-04-visual-summary.txt

Delete Temporary Files

# Delete obsolete working docs
rm work/status.md
rm work/notes.md

# Or clean everything
rm -rf work/*
# (work/README.md is safe - in .gitignore exception)

Verify Clean State

# Root should only have these:
ls *.md
# README.md
# AGENTS.md
# (CHANGELOG.md when created)

# work/ should be empty (except README.md)
ls work/
# README.md

Commit Changes
- Commit new permanent docs
- Commit archived docs
- Note: work/ contents not committed (gitignored)

Example Cleanup

# Before cleanup (messy root!)
ls *.md
# README.md
# AGENTS.md
# CURRENT_STATUS.md
# DIATAXIS_MIGRATION.md
# SUMMARY.md
# SESSION_NOTES.md
# ... (many more)

# After cleanup (clean root!)
ls *.md
# README.md
# AGENTS.md

# Working files in work/ during session
ls work/
# README.md
# session-notes.md
# status.md

# After session cleanup
ls work/
# README.md
# (all session files archived or deleted)

# Archived
ls docs/archive/ | tail -5
# 2025-11-04-diataxis-migration.md
# 2025-11-04-diataxis-complete.md
# 2025-11-04-diataxis-migration-visual.txt
# 2025-11-04-session-summary.md
# ...

# Permanent docs in Diátaxis structure
ls docs/tutorials/
# getting-started.md
# first-audit.md

ls docs/how-to/
# nix-flakes.md
# deploy.md

🚨 Common Gotchas

Nix Flakes

Always use nix develop, not nix-shell

# ✅ Correct
cd grasp-audit
nix develop
nix develop -c cargo build

# ❌ Wrong
nix-shell
nix-shell --run "cargo build"

Why: We use flake.nix, not shell.nix. See docs/learnings/nix-flakes.md.

Flake Commands:

# Show flake outputs
nix flake show

# Update flake inputs
nix flake update

# Build package
nix build

# Run package
nix run

Git Subprojects

grasp-audit is a subproject with its own flake

# ✅ Correct - enter grasp-audit environment
cd grasp-audit
nix develop
cargo build

# ❌ Wrong - can't build from root
cd ngit-grasp
cargo build  # This won't find grasp-audit

Why: grasp-audit/ has its own Cargo.toml and flake.nix.

nostr-sdk Versions

We use nostr-sdk 0.43.x (latest stable)

# ✅ Correct
[dependencies]
nostr-sdk = "0.43"

# ❌ Wrong
nostr-sdk = "0.35"  # Old version, breaking changes

Why: We upgraded from 0.35 to 0.43. See docs/learnings/nostr-sdk.md for migration notes.

Common Breaking Changes:

EventBuilder::new() signature changed
Tag API changed to Tag::custom()
Filter API changed
See archived upgrade docs for details

Testing Patterns

Integration tests require relay

# ✅ Correct - start relay first
docker run --rm -p 7000:7000 scsibug/nostr-rs-relay

# Then run tests
cd grasp-audit
nix develop -c cargo test --ignored

# ❌ Wrong - integration tests will fail
cargo test --ignored  # No relay running

Test Organization:

// Unit tests (no relay needed)
#[cfg(test)]
mod tests {
    #[test]
    fn test_something() { }
}

// Integration tests (relay required)
#[cfg(test)]
mod tests {
    #[test]
    #[ignore]  // Requires relay
    fn test_against_relay() { }
}

Documentation Updates

Keep README.md synchronized

When you:

Complete a major feature → Update README.md status
Change architecture → Update docs/ARCHITECTURE.md
Add dependencies → Update README.md tech stack
Change workflow → Update docs/GETTING_STARTED.md

Don't:

Create duplicate documentation
Leave stale status markers
Forget to update CHANGELOG.md for user-facing changes

📄 File Format Guidelines

When to Use .txt Files

Use .txt ONLY for:

ASCII art visual summaries
Box diagrams with Unicode characters
Terminal-style status displays

Examples of appropriate .txt content:

╔════════════════════════════════════════╗
║  STATUS: ✅ COMPLETE                   ║
╚════════════════════════════════════════╝

Rules:

✅ Create in root during session for visual impact
✅ Archive immediately after session ends
✅ Use descriptive names: CLEANUP_VISUAL_SUMMARY.txt
❌ Never keep .txt files in root long-term
❌ Don't use .txt for regular documentation
❌ Don't duplicate information (use .md instead)

Lifecycle:

Create .txt → Use in session → Archive immediately

When to Use .md Files

Use .md for ALL documentation:

Architecture docs
Session summaries
Status reports
Learnings
Planning documents
API documentation
User guides

Why markdown is preferred:

Renders nicely on GitHub/GitLab
Supports code blocks with syntax highlighting
Easy to link between documents
Better for long-form content
Version control friendly

📝 Writing Guidelines

Markdown Style

# Title (H1 - only one per file)

**Date:** YYYY-MM-DD  
**Status:** [WIP|COMPLETE|ARCHIVED]

## Section (H2)

### Subsection (H3)

**Bold** for emphasis, `code` for commands/code.

- Bullet lists for items
- Keep consistent style

1. Numbered lists for sequences
2. Use when order matters

✅ Use emoji for status (sparingly)
❌ Don't overuse emoji

\`\`\`bash
# Code blocks with language
cargo build
\`\`\`

Status Markers

[WIP] - Work in progress
[COMPLETE] - Finished, may be archived
[ARCHIVED] - Moved to archive, historical only
✅ - Success/complete
❌ - Failure/incorrect
⏳ - In progress
🔜 - Planned/next

Document Headers

# Document Title

**Purpose:** One-line purpose  
**Date:** YYYY-MM-DD  
**Status:** [WIP|COMPLETE|ARCHIVED]  
**Related:** Links to related docs

---

## Content starts here

🤖 AI Agent Responsibilities

Before Creating New Documents

Check if document already exists
```
find . -name "*keyword*.md"
```
Check if information can be added to existing doc
- Prefer updating over creating
- Use sections/subsections
Determine correct location
- Session-specific? → work/ (temporary, gitignored)
- Teaching beginners? → docs/tutorials/
- Solving a problem? → docs/how-to/
- Technical reference? → docs/reference/
- Explaining concepts? → docs/explanation/
- Historical? → docs/archive/
Ask the Diátaxis questions:
- "Can you teach me to...?" → Tutorial
- "How do I...?" → How-To
- "What is...?" → Reference
- "Why...?" → Explanation
Use descriptive names
- Working docs: session-notes.md, status.md (in work/)
- Archived docs: YYYY-MM-DD-description.md (in docs/archive/)
- Tutorials: getting-started.md, first-audit.md
- How-To: deploy.md, nix-flakes.md
- Reference: configuration.md, api.md
- Explanation: architecture.md, decisions.md
Choose correct file format
- Use .md for all documentation (default)
- Use .txt ONLY for ASCII art visual summaries
- Archive .txt files immediately after session

During Development

Update status markers
- Mark WIP → COMPLETE when done
- Update README.md status section
Extract learnings as you go
- Add gotchas to docs/learnings/
- Don't wait until cleanup
Keep documentation DRY
- Link to existing docs
- Don't duplicate information

End of Session

Clean up work/ directory (MANDATORY)
- Archive valuable session docs to docs/archive/YYYY-MM-DD-*.md
- Delete temporary status reports
- Extract content to Diátaxis categories if needed
- Verify work/ is empty (except README.md)
Create session summary (if valuable)
- Archive to docs/archive/YYYY-MM-DD-session-summary.md
- Include: accomplishments, next steps, blockers
Update permanent docs
- Sync README.md with reality
- Update relevant docs/ files
- Commit changes

Verify clean state

ls *.md  # Should only show README.md, AGENTS.md
ls work/  # Should only show README.md

Cleanup Time (End of Session)

Review work/ directory
```
ls -la work/
```
Extract content to appropriate Diátaxis category:
- Gotchas/solutions → docs/how-to/
- Technical facts → docs/reference/
- Concepts/design → docs/explanation/
- Lessons → docs/tutorials/

Archive valuable session docs

mv work/important-notes.md docs/archive/2025-11-04-session-notes.md
mv work/visual-summary.txt docs/archive/2025-11-04-visual-summary.txt

Delete temporary files

rm work/status.md
rm work/temp-notes.md

Verify clean state

ls *.md  # Only README.md, AGENTS.md
ls work/  # Only README.md

Commit permanent changes
- Commit new/updated permanent docs
- Commit archived docs
- Note: work/ not committed (gitignored)

🎯 Quality Checklist

For Every Document

Clear purpose stated at top
Date included
Status marker present
Proper heading hierarchy (H1 → H2 → H3)
Code blocks have language specified
Links are valid and relative
No duplicate information
Spell-checked and readable

For Working Documents

Descriptive filename with date
Will be archived or deleted when done
Not duplicating permanent docs
Learnings extracted to docs/learnings/

For Permanent Documents

In correct docs/ subdirectory
Linked from docs/README.md
Updated as project evolves
No session-specific details
Serves long-term purpose

For Archived Documents

Moved to docs/archive/
Renamed with date prefix
ARCHIVED marker at top (for .md files)
Learnings extracted first (for .md files)
Not referenced in active docs

For .txt Files

Contains only ASCII art/visual summaries
Created in root for session use
Archived immediately after session
Not used for regular documentation
Descriptive filename with purpose clear

📚 Reference Documents

Must Read

This file (AGENTS.md) - Guidelines for documentation
README.md - Project overview
docs/README.md - Documentation navigation

Key Technical Docs

docs/ARCHITECTURE.md - System design
docs/TEST_STRATEGY.md - Testing approach
docs/GETTING_STARTED.md - Setup guide

Learnings (Gotchas)

docs/learnings/nix-flakes.md - Nix flake patterns
docs/learnings/nostr-sdk.md - nostr-sdk notes
docs/learnings/git-http-backend.md - Git protocol tips

🔗 Quick Links

💡 Tips for Success

Less is more - Prefer updating over creating
Archive often - Keep root clean
Extract learnings - Make knowledge reusable
Link, don't duplicate - DRY applies to docs too
Date everything - Context is important
Use descriptive names - Future you will thank you
Check before creating - Document might already exist
Update as you go - Don't wait for cleanup time
Use .md by default - Only use .txt for ASCII art
Archive .txt immediately - Don't let them linger

🚀 Next Steps

After reading this:

Review current documentation structure
```
ls -la *.md
ls -la docs/
```
Identify cleanup candidates
- Completed working docs
- Obsolete duplicates
- Session summaries
Extract learnings
- Review completed docs
- Add to docs/learnings/
Archive and clean
- Move to docs/archive/
- Delete obsolete files
- Update links

Commit changes

git add .
git commit -m "docs: cleanup and reorganization"

Remember: Good documentation structure is like good code structure - it makes everything easier.

Last updated: November 4, 2025
Status: ✅ Active guidelines

21 KiB Raw Blame History

AI Agent Guidelines for ngit-grasp

📁 Documentation Structure

Overview

Diátaxis Framework

File Type Guidelines

📋 Document Lifecycle

1. Working Documents (work/ Directory)

2. Permanent Documentation (docs/)

3. Archive (docs/archive/)

4. Learnings (DEPRECATED)

🔄 Cleanup Process

When to Clean Up

Cleanup Steps

Example Cleanup

🚨 Common Gotchas

Nix Flakes

Git Subprojects

nostr-sdk Versions

Testing Patterns

Documentation Updates

📄 File Format Guidelines

When to Use .txt Files

When to Use .md Files

📝 Writing Guidelines

Markdown Style

Status Markers

Document Headers

🤖 AI Agent Responsibilities

Before Creating New Documents

During Development

End of Session

Cleanup Time (End of Session)

🎯 Quality Checklist

For Every Document

For Working Documents

For Permanent Documents

For Archived Documents

For .txt Files

📚 Reference Documents

Must Read

Key Technical Docs

Learnings (Gotchas)

🔗 Quick Links

💡 Tips for Success

🚀 Next Steps

21 KiB

Raw Blame History