Skill: athola/nm-sanctum-update-readme (version 1.0.2)

--- name: update-readme description: | Refresh README structure and content using repo context from git-workspace-review version: 1.9.5 triggers: - readme - documentation - exemplars - research - structure metadata: {"openclaw": {"homepage": "https://github.com/athola/claude-night-market/tree/master/plugins/sanctum", "emoji": "\ud83e\udd9e", "requires": {"config": ["night-market.sanctum:shared", "night-market.sanctum:git-workspace-review", "night-market.imbue:proof-of-work", "night-market.scribe:slop-detector", "night-market.scribe:doc-generator"]}}} source: claude-night-market source_plugin: sanctum --- > **Night Market Skill** — ported from [claude-night-market/sanctum](https://github.com/athola/claude-night-market/tree/master/plugins/sanctum). For the full experience with agents, hooks, and commands, install the Claude Code plugin. # README Update Workflow ## When To Use Use this skill whenever the README requires a structural refresh. Run `Skill(sanctum:git-workspace-review)` first to capture repo context and diffs. ## When NOT To Use - Updating inline docs: use doc-updates - Consolidating ephemeral reports: use doc-consolidation ## Required TodoWrite Items 1. `update-readme:language-audit` 2. `update-readme:exemplar-research` 3. `update-readme:outline-aligned` 4. `update-readme:edits-applied` 5. `update-readme:slop-scanned` - AI marker detection via scribe 6. `update-readme:verification-reporting` ## Step 1 - Language Audit (`update-readme:language-audit`) - Confirm `pwd`, `git status -sb`, and the baseline branch for reference. - Detect dominant languages using repository heuristics (manifest files, file counts). - Note secondary languages that influence documentation (e.g., a TypeScript frontend and a Rust backend) so the README can surface both. - Record the method and findings. See `modules/language-audit.md` for detailed detection patterns and commands. ## Step 2 - Exemplar Research (`update-readme:exemplar-research`) - For each primary and secondary language, use web search to locate high-quality READMEs (star count, recency, maintainer activity). - Capture 2-3 exemplar repositories per language and summarize why each is relevant (section order, visuals, quickstart clarity, governance messaging, math exposition, etc.). - Store citations for every exemplar so the final summary references them explicitly. See `modules/exemplar-research.md` for search query patterns and evaluation criteria. ## Step 3 - Outline Alignment (`update-readme:outline-aligned`) - Compare current README headings (`rg -n '^#' README.md`) against patterns observed in exemplars. - Draft a target outline covering: value proposition, installation, quickstart, deeper usage/configuration, architecture/feature highlights, performance or math guarantees, documentation links, contribution/governance, roadmap/status, and licensing/security notes. - validate internal documents (docs/, specs/, wiki, commands/) are mapped to the relevant sections so the README anchors them with context-sensitive links. ## Step 4 - Apply Edits (`update-readme:edits-applied`) - Implement the new structure directly in `README.md` (or the specified file). - Follow `Skill(leyline:markdown-formatting)` conventions: wrap prose at 80 chars (prefer sentence/clause boundaries), blank lines around headings, ATX headings only, blank line before lists, reference-style links for long URLs. - Maintain concise, evidence-based prose; avoid marketing fluff. - Add comparison tables, feature lists, or diagrams only if they originate from current repository assets (no speculative content). - When referencing algorithms or performance claims, point to benchmarks or tests within the repository or documented math reviews. ## Step 4.5 - AI Slop Detection (`update-readme:slop-scanned`) Run `Skill(scribe:slop-detector)` on the updated README to detect AI-generated content markers. ### Scribe Integration The scribe plugin provides AI slop detection: ``` Skill(scribe:slop-detector) --target README.md ``` This detects: - **Tier 1 words**: delve, tapestry, comprehensive, leveraging, etc. - **Phrase patterns**: "In today's fast-paced world", "cannot be overstated" - **Structural markers**: Excessive em dashes, bullet overuse, sentence uniformity - **Marketing language**: "enterprise-ready", "cutting-edge", "seamless" ### Remediation If slop score exceeds 2.0 (moderate), apply `Skill(scribe:doc-generator)` principles: 1. Ground every claim with specifics 2. Remove formulaic openers/closers 3. Use numbers, commands, filenames over adjectives 4. Balance bullets with narrative prose 5. Show authorial perspective (trade-offs, reasoning) For significant cleanup needs, use: ``` Agent(scribe:doc-editor) --target README.md ``` ## Step 5 - Verification & Reporting (`update-readme:verification-reporting`) - Re-read the updated README for clarity, accessibility (section lengths, bullet balance), and accurate links. - Run `git diff README.md` (or the edited file) and capture snippets for the final report. - Summarize detected languages, exemplar sources (with citations), key structural decisions, and follow-up TODOs (e.g., add badges, upload diagrams). ## Exit Criteria - All `TodoWrite` items are complete. - The README reflects a modern, language-aware structure, referencing both internal docs and external inspiration with citations. - Research notes and command references are captured so future reviewers can reproduce the process. ## Troubleshooting ### Common Issues **Documentation out of sync** Run `make docs-update` to regenerate from code **Build failures** Check that all required dependencies are installed **Links broken** Verify relative paths in documentation files

path: modules/exemplar-research.md
content: # Exemplar Research Patterns

Detailed patterns for finding, evaluating, and documenting high-quality README exemplars.

## Web Search Query Patterns

### Language-Specific Queries

```
"GitHub [language] README best practices"
"[language] framework README examples"
"[language] project README badges"
"[language] library documentation structure"
"awesome [language] README"
```

### Framework/Domain-Specific Queries

```
"[framework] README structure"
"[domain] project README examples" (e.g., "CLI tool README examples")
"[language] [project-type] documentation" (e.g., "Rust async library documentation")
```

### Quality Indicators

```
"high star count [language] README"
"well-maintained [language] project README"
"[language] project documentation best practices 2024"
```

## Exemplar Evaluation Criteria

Assess each candidate README using these dimensions:

### Structure & Organization
- **Section order**: Does it follow a logical progression (value → quickstart → details)?
- **Progressive disclosure**: Are complex topics deferred until after basics?
- **Table of contents**: Is it present and well-structured?
- **Visual hierarchy**: Clear heading levels, spacing, readability?

### Content Quality
- **Value proposition**: Clear statement of what the project does and why it matters?
- **Quickstart clarity**: Can a new user get started in <5 minutes?
- **Code examples**: Are they runnable, realistic, well-commented?
- **Installation steps**: Clear, tested, platform-aware?

### Technical Communication
- **Accuracy**: Does it match the actual codebase capabilities?
- **Completeness**: Coverage of installation, usage, configuration, troubleshooting?
- **Governance messaging**: Clear contribution guidelines, roadmap, support channels?
- **Math/algorithm exposition**: For technical projects, is the theory well-explained?

### Maintenance Signals
- **Recency**: Last commit within 6 months?
- **Star count**: Indicator of community validation (>500 stars preferred)
- **Maintainer activity**: Active issue responses, recent releases?
- **CI/CD badges**: Evidence of automated quality checks?

## Citation Format

Record each exemplar with full attribution:

```markdown
### Exemplar: [Project Name]
- **URL**: https://github.com/[org]/[repo]
- **Language**: [Primary language]
- **Stars**: [count] (as of [date])
- **Last Updated**: [date]
- **Relevant Patterns**:
  - [Pattern 1]: [Description and why it's relevant]
  - [Pattern 2]: [Description and why it's relevant]
  - [Pattern 3]: [Description and why it's relevant]
- **Specific Elements to Adapt**:
  - [Element]: [How it applies to this project]
```

## Storage Recommendations

### Temporary Research Notes
Store research findings in a temporary file during the session:

```bash
# Create research notes file
cat > /tmp/readme-research.md << 'EOF'
# README Exemplar Research

## [Language 1] Exemplars
[Citations...]

## [Language 2] Exemplars
[Citations...]
EOF
```

### Final Report Integration
Include exemplar citations in the final verification report so future maintainers can:
- Understand the design decisions
- Revisit the sources for updates
- Validate the approach against current best practices

## Example Multi-Language Research

For a project with Rust backend + TypeScript frontend:

1. **Rust Exemplars** (2-3 projects)
   - Focus on: CLI tool patterns, installation via cargo, feature flags, performance claims

2. **TypeScript Exemplars** (2-3 projects)
   - Focus on: npm installation, dev environment setup, API documentation, framework integration

3. **Full-Stack Exemplars** (1-2 projects)
   - Focus on: How to structure README for multiple runtimes, quickstart for both components, architecture diagrams

## Quality Threshold

Minimum criteria for an exemplar to be useful:
- Must have >100 stars OR be from a recognized organization
- README must be >200 lines (substantial content)
- Must have been updated in the last year
- Must demonstrate at least 3 structural patterns relevant to the target project


path: modules/language-audit.md
content: # Language Audit Patterns

Detailed patterns and commands for detecting project languages and their documentation implications.

## Manifest File Detection

Check for language-specific manifest files to identify the primary language(s):

```bash
# Rust
ls -1 Cargo.toml 2>/dev/null

# Node.js/TypeScript
ls -1 package.json 2>/dev/null

# Go
ls -1 go.mod 2>/dev/null

# Python
ls -1 pyproject.toml setup.py requirements.txt 2>/dev/null

# Java/Kotlin
ls -1 pom.xml build.gradle build.gradle.kts 2>/dev/null

# Ruby
ls -1 Gemfile 2>/dev/null

# PHP
ls -1 composer.json 2>/dev/null
```

## File Count Analysis

Count source files by extension to determine language distribution:

```bash
# Rust
git ls-files | rg '\.rs$' | wc -l
# or for preview
rg --files -g '*.rs' | head -10

# Python
git ls-files | rg '\.py$' | wc -l
rg --files -g '*.py' | head -10

# Go
git ls-files | rg '\.go$' | wc -l
rg --files -g '*.go' | head -10

# TypeScript/JavaScript
git ls-files | rg '\.(ts|tsx|js|jsx)$' | wc -l
rg --files -g '*.ts' -g '*.tsx' | head -10

# Java
git ls-files | rg '\.java$' | wc -l
rg --files -g '*.java' | head -10
```

## Language Priority Heuristics

Determine primary language using these priority rules:

1. **Manifest presence**: If a language-specific manifest exists, it's a strong signal
2. **File count dominance**: Language with >60% of source files is primary
3. **Directory structure**: Check for language-specific directories (src/, lib/, pkg/)
4. **Build configuration**: Presence of Makefile, CMakeLists.txt, or build scripts

## Secondary Language Handling

Document secondary languages when they:

- Represent >20% of codebase
- Serve distinct architectural roles (e.g., Rust backend + TypeScript frontend)
- Have their own build/test infrastructure
- Require separate installation or runtime considerations

### Example Multi-Language Documentation Strategy

```markdown
## Installation

### Backend (Rust)
[Rust-specific instructions]

### Frontend (TypeScript)
[Node/npm-specific instructions]
```

## Recording Findings

Capture the audit results in a structured format:

```
Language Audit Results:
- Primary: [Language] ([count] files, [manifest])
- Secondary: [Language] ([count] files, [manifest])
- Method: [manifest detection | file count | directory structure]
- Documentation implications: [single-language | multi-language sections needed]
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)