migrate mosaic home to xdg config path
This commit is contained in:
Jason Woltje
@@ -1,10 +1,10 @@
|
||||
# Mosaic Universal Standards (Machine-Wide)
|
||||
|
||||
Before applying any runtime-specific guidance in this file, load and apply:
|
||||
- `~/.mosaic/STANDARDS.md`
|
||||
- `~/.config/mosaic/STANDARDS.md`
|
||||
- project-local `AGENTS.md`
|
||||
|
||||
`~/.mosaic` is the canonical cross-agent standards layer. This `CLAUDE.md` is an adapter layer for Claude-specific capabilities only.
|
||||
`~/.config/mosaic` is the canonical cross-agent standards layer. This `CLAUDE.md` is an adapter layer for Claude-specific capabilities only.
|
||||
|
||||
---
|
||||
|
||||
@@ -17,11 +17,11 @@ Before applying any runtime-specific guidance in this file, load and apply:
|
||||
|
||||
## Skills System
|
||||
|
||||
**Skills are available in `~/.mosaic/skills/`.** Skills are instruction packages that provide domain expertise from `mosaic/agent-skills` plus local Mosaic skills.
|
||||
**Skills are available in `~/.config/mosaic/skills/`.** Skills are instruction packages that provide domain expertise from `mosaic/agent-skills` plus local Mosaic skills.
|
||||
|
||||
**Load a skill by reading its SKILL.md:**
|
||||
```
|
||||
Read ~/.mosaic/skills/<skill-name>/SKILL.md
|
||||
Read ~/.config/mosaic/skills/<skill-name>/SKILL.md
|
||||
```
|
||||
|
||||
### Skill Dispatch Table — Load the right skills for your task
|
||||
@@ -66,7 +66,7 @@ Read ~/.mosaic/skills/<skill-name>/SKILL.md
|
||||
|
||||
When spawning workers via `claude -p`, include skill loading in the kickstart:
|
||||
```bash
|
||||
claude -p "Read ~/.mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
|
||||
claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
|
||||
```
|
||||
|
||||
For Ralph prd.json stories, add a `skills` field:
|
||||
@@ -118,7 +118,7 @@ claude -p "Implement US-001 from prd.json following Ralph pattern"
|
||||
2. Convert to Ralph: `Load the ralph skill and convert tasks/prd-[name].md to prd.json`
|
||||
3. Run Ralph: `./scripts/ralph/ralph.sh`
|
||||
|
||||
**For full Ralph guide:** `~/.mosaic/guides/ralph-autonomous.md`
|
||||
**For full Ralph guide:** `~/.config/mosaic/guides/ralph-autonomous.md`
|
||||
|
||||
## AGENTS.md Pattern
|
||||
|
||||
@@ -148,40 +148,40 @@ When starting work on a **new project** that lacks `CLAUDE.md` or `AGENTS.md`, b
|
||||
|
||||
```bash
|
||||
# Automated (recommended)
|
||||
~/.mosaic/rails/bootstrap/init-project.sh --name "Project Name" --type auto
|
||||
~/.config/mosaic/rails/bootstrap/init-project.sh --name "Project Name" --type auto
|
||||
|
||||
# Or manually with templates
|
||||
export PROJECT_NAME="Project Name" PROJECT_DESCRIPTION="What it does" TASK_PREFIX="PN"
|
||||
envsubst < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
|
||||
envsubst < ~/.mosaic/templates/agent/AGENTS.md.template > AGENTS.md
|
||||
envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
|
||||
envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
|
||||
```
|
||||
|
||||
**Available project types:** `nestjs-nextjs`, `django`, `typescript`, `python-fastapi`, `python-library`, `generic` (auto-detected from project files).
|
||||
|
||||
**Templates:** `~/.mosaic/templates/agent/` (generic) and `~/.mosaic/templates/agent/projects/<type>/` (tech-stack specific).
|
||||
**Templates:** `~/.config/mosaic/templates/agent/` (generic) and `~/.config/mosaic/templates/agent/projects/<type>/` (tech-stack specific).
|
||||
|
||||
**Fragments:** `~/.mosaic/templates/agent/fragments/` — Reusable sections (conditional-loading, commit-format, secrets, multi-agent, code-review).
|
||||
**Fragments:** `~/.config/mosaic/templates/agent/fragments/` — Reusable sections (conditional-loading, commit-format, secrets, multi-agent, code-review).
|
||||
|
||||
**Full guide:** `~/.mosaic/guides/bootstrap.md`
|
||||
**Full guide:** `~/.config/mosaic/guides/bootstrap.md`
|
||||
|
||||
### Agent Configuration Health
|
||||
|
||||
```bash
|
||||
# Audit all projects for missing CLAUDE.md, AGENTS.md, agent-guide references
|
||||
~/.mosaic/rails/bootstrap/agent-lint.sh
|
||||
~/.config/mosaic/rails/bootstrap/agent-lint.sh
|
||||
|
||||
# Audit with fix suggestions
|
||||
~/.mosaic/rails/bootstrap/agent-lint.sh --verbose --fix-hint
|
||||
~/.config/mosaic/rails/bootstrap/agent-lint.sh --verbose --fix-hint
|
||||
|
||||
# Non-destructively upgrade existing projects (inject missing sections)
|
||||
~/.mosaic/rails/bootstrap/agent-upgrade.sh --all --dry-run # Preview
|
||||
~/.mosaic/rails/bootstrap/agent-upgrade.sh --all # Apply
|
||||
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh --all --dry-run # Preview
|
||||
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh --all # Apply
|
||||
|
||||
# Upgrade a single project
|
||||
~/.mosaic/rails/bootstrap/agent-upgrade.sh ~/src/my-project
|
||||
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh ~/src/my-project
|
||||
```
|
||||
|
||||
**Spec:** `~/.mosaic/templates/agent/SPEC.md` — Defines Tier 1/2/3 requirements for well-configured projects.
|
||||
**Spec:** `~/.config/mosaic/templates/agent/SPEC.md` — Defines Tier 1/2/3 requirements for well-configured projects.
|
||||
|
||||
## Issue Tracking (Git-Based)
|
||||
|
||||
@@ -210,7 +210,7 @@ Use consistent labels across projects:
|
||||
- Post-release: `X.0.0` for breaking changes
|
||||
|
||||
### Git Scripts (PREFERRED for Gitea/GitHub operations)
|
||||
Cross-platform helpers at `~/.mosaic/rails/git/` (work with both Gitea and GitHub):
|
||||
Cross-platform helpers at `~/.config/mosaic/rails/git/` (work with both Gitea and GitHub):
|
||||
|
||||
**Why use these scripts?**
|
||||
- ✅ Auto-detect platform (Gitea vs GitHub)
|
||||
@@ -220,37 +220,37 @@ Cross-platform helpers at `~/.mosaic/rails/git/` (work with both Gitea and GitHu
|
||||
|
||||
**Issues:**
|
||||
```bash
|
||||
~/.mosaic/rails/git/issue-create.sh -t "Title" -l "label" -m "0.2.0"
|
||||
~/.mosaic/rails/git/issue-list.sh -s open -l "bug"
|
||||
~/.mosaic/rails/git/issue-list.sh -m "M6-AgentOrchestration" # Works with milestone names!
|
||||
~/.mosaic/rails/git/issue-view.sh -i 42 # View issue details
|
||||
~/.mosaic/rails/git/issue-edit.sh -i 42 -t "New Title" -l "labels"
|
||||
~/.mosaic/rails/git/issue-assign.sh -i 42 -a "username"
|
||||
~/.mosaic/rails/git/issue-comment.sh -i 42 -c "Comment text"
|
||||
~/.mosaic/rails/git/issue-close.sh -i 42 [-c "Closing comment"]
|
||||
~/.mosaic/rails/git/issue-reopen.sh -i 42 [-c "Reopening reason"]
|
||||
~/.config/mosaic/rails/git/issue-create.sh -t "Title" -l "label" -m "0.2.0"
|
||||
~/.config/mosaic/rails/git/issue-list.sh -s open -l "bug"
|
||||
~/.config/mosaic/rails/git/issue-list.sh -m "M6-AgentOrchestration" # Works with milestone names!
|
||||
~/.config/mosaic/rails/git/issue-view.sh -i 42 # View issue details
|
||||
~/.config/mosaic/rails/git/issue-edit.sh -i 42 -t "New Title" -l "labels"
|
||||
~/.config/mosaic/rails/git/issue-assign.sh -i 42 -a "username"
|
||||
~/.config/mosaic/rails/git/issue-comment.sh -i 42 -c "Comment text"
|
||||
~/.config/mosaic/rails/git/issue-close.sh -i 42 [-c "Closing comment"]
|
||||
~/.config/mosaic/rails/git/issue-reopen.sh -i 42 [-c "Reopening reason"]
|
||||
```
|
||||
|
||||
**Pull Requests:**
|
||||
```bash
|
||||
~/.mosaic/rails/git/pr-create.sh -t "Title" -b "Description" -i 42
|
||||
~/.mosaic/rails/git/pr-create.sh -t "Title" -B main -H feature-branch
|
||||
~/.mosaic/rails/git/pr-list.sh -s open
|
||||
~/.mosaic/rails/git/pr-view.sh -n 42 # View PR details
|
||||
~/.mosaic/rails/git/pr-review.sh -n 42 -a approve [-c "LGTM"]
|
||||
~/.mosaic/rails/git/pr-review.sh -n 42 -a request-changes -c "Fix X"
|
||||
~/.mosaic/rails/git/pr-merge.sh -n 42 -m squash -d
|
||||
~/.mosaic/rails/git/pr-close.sh -n 42 [-c "Closing reason"]
|
||||
~/.mosaic/rails/git/pr-diff.sh -n 42 [-o diff.patch] # Get PR diff
|
||||
~/.mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json] # Get PR metadata as JSON
|
||||
~/.config/mosaic/rails/git/pr-create.sh -t "Title" -b "Description" -i 42
|
||||
~/.config/mosaic/rails/git/pr-create.sh -t "Title" -B main -H feature-branch
|
||||
~/.config/mosaic/rails/git/pr-list.sh -s open
|
||||
~/.config/mosaic/rails/git/pr-view.sh -n 42 # View PR details
|
||||
~/.config/mosaic/rails/git/pr-review.sh -n 42 -a approve [-c "LGTM"]
|
||||
~/.config/mosaic/rails/git/pr-review.sh -n 42 -a request-changes -c "Fix X"
|
||||
~/.config/mosaic/rails/git/pr-merge.sh -n 42 -m squash -d
|
||||
~/.config/mosaic/rails/git/pr-close.sh -n 42 [-c "Closing reason"]
|
||||
~/.config/mosaic/rails/git/pr-diff.sh -n 42 [-o diff.patch] # Get PR diff
|
||||
~/.config/mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json] # Get PR metadata as JSON
|
||||
```
|
||||
|
||||
**Milestones:**
|
||||
```bash
|
||||
~/.mosaic/rails/git/milestone-create.sh -t "0.2.0" -d "Description"
|
||||
~/.mosaic/rails/git/milestone-create.sh --list
|
||||
~/.mosaic/rails/git/milestone-list.sh [-s open|closed|all]
|
||||
~/.mosaic/rails/git/milestone-close.sh -t "0.2.0"
|
||||
~/.config/mosaic/rails/git/milestone-create.sh -t "0.2.0" -d "Description"
|
||||
~/.config/mosaic/rails/git/milestone-create.sh --list
|
||||
~/.config/mosaic/rails/git/milestone-list.sh [-s open|closed|all]
|
||||
~/.config/mosaic/rails/git/milestone-close.sh -t "0.2.0"
|
||||
```
|
||||
|
||||
**NOTE:** These scripts handle the Gitea `--milestones` (plural) syntax automatically. Always prefer these over raw `tea` or `gh` commands.
|
||||
@@ -303,7 +303,7 @@ woodpecker secret rm <owner/repo> -n KEY # Delete secret
|
||||
**Setup command:** `woodpecker setup --server https://ci.mosaicstack.dev --token "YOUR_TOKEN"`
|
||||
|
||||
### Portainer Scripts
|
||||
CLI tools for managing Portainer stacks at `~/.mosaic/rails/portainer/`.
|
||||
CLI tools for managing Portainer stacks at `~/.config/mosaic/rails/portainer/`.
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
@@ -345,9 +345,9 @@ endpoint-list.sh -f json # JSON format
|
||||
|
||||
**Common Workflow (CI/CD redeploy):**
|
||||
```bash
|
||||
~/.mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
|
||||
~/.mosaic/rails/portainer/stack-status.sh -n myapp && \
|
||||
~/.mosaic/rails/portainer/stack-logs.sh -n myapp -s api -t 50
|
||||
~/.config/mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
|
||||
~/.config/mosaic/rails/portainer/stack-status.sh -n myapp && \
|
||||
~/.config/mosaic/rails/portainer/stack-logs.sh -n myapp -s api -t 50
|
||||
```
|
||||
|
||||
### Git Worktrees
|
||||
@@ -398,7 +398,7 @@ git worktree remove ../my-app_worktrees/42-fix-login
|
||||
- Never disable lint rules (`eslint-disable`, `noqa`, `nolint`)
|
||||
- Never leave warnings — warnings are errors you haven't fixed yet
|
||||
- If you touched a file, you own its lint violations (Campsite Rule)
|
||||
- If unsure what linter the project uses, read the `lint` skill: `~/.mosaic/skills/lint/SKILL.md`
|
||||
- If unsure what linter the project uses, read the `lint` skill: `~/.config/mosaic/skills/lint/SKILL.md`
|
||||
|
||||
### Code Style
|
||||
Follow [Google Style Guides](https://github.com/google/styleguide) for all languages.
|
||||
@@ -443,30 +443,30 @@ When working on issue #N, create `docs/scratchpads/N-short-name.md`:
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping a new project | `~/.mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous task completion | `~/.mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
|
||||
| Frontend development | `~/.mosaic/guides/frontend.md` |
|
||||
| Backend/API development | `~/.mosaic/guides/backend.md` |
|
||||
| Code review | `~/.mosaic/guides/code-review.md` |
|
||||
| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
|
||||
| CI/CD pipelines & Docker builds | `~/.mosaic/guides/ci-cd-pipelines.md` |
|
||||
| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
|
||||
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
|
||||
| Bootstrapping a new project | `~/.config/mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous task completion | `~/.config/mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
|
||||
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
|
||||
| Code review | `~/.config/mosaic/guides/code-review.md` |
|
||||
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
|
||||
| CI/CD pipelines & Docker builds | `~/.config/mosaic/guides/ci-cd-pipelines.md` |
|
||||
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
|
||||
| Secrets management | See section below |
|
||||
|
||||
**Project-specific skills:**
|
||||
|
||||
| Project | Skill |
|
||||
|---------|-------|
|
||||
| jetrich/jarvis | `~/.mosaic/skills/jarvis/SKILL.md` |
|
||||
| jetrich/jarvis | `~/.config/mosaic/skills/jarvis/SKILL.md` |
|
||||
|
||||
## Secrets Management
|
||||
|
||||
**NEVER hardcode secrets in the codebase.** Choose the appropriate method based on your environment.
|
||||
|
||||
### If Using Vault
|
||||
See `~/.mosaic/guides/vault-secrets.md` for the canonical structure and rules.
|
||||
See `~/.config/mosaic/guides/vault-secrets.md` for the canonical structure and rules.
|
||||
|
||||
Quick reference:
|
||||
```
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "~/.mosaic/rails/qa/qa-hook-stdin.sh",
|
||||
"command": "~/.config/mosaic/rails/qa/qa-hook-stdin.sh",
|
||||
"timeout": 60
|
||||
}
|
||||
]
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Mosaic Runtime Adapter — OpenCode
|
||||
|
||||
Load and apply in this order:
|
||||
1. `~/.mosaic/STANDARDS.md`
|
||||
1. `~/.config/mosaic/STANDARDS.md`
|
||||
2. repo-local `AGENTS.md` (and `SOUL.md` when present)
|
||||
|
||||
This file is an OpenCode adapter layer. It does not replace project guidance.
|
||||
@@ -10,19 +10,19 @@ This file is an OpenCode adapter layer. It does not replace project guidance.
|
||||
|
||||
- OpenCode sessions may not expose a native subagent/background task primitive in all deployments.
|
||||
- When native subagent delegation is unavailable, use Mosaic's deterministic orchestrator rail:
|
||||
- `~/.mosaic/bin/mosaic-orchestrator-matrix-cycle`
|
||||
- `~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle`
|
||||
- Keep repo task tracking in `docs/tasks.md` as the canonical human-readable state.
|
||||
- Keep machine transport/controller state in `.mosaic/orchestrator/`.
|
||||
|
||||
## Fallback Delegation Mode (No Native Subagents)
|
||||
|
||||
1. Bootstrap repo if needed:
|
||||
- `~/.mosaic/bin/mosaic-bootstrap-repo /path/to/repo`
|
||||
- `~/.config/mosaic/bin/mosaic-bootstrap-repo /path/to/repo`
|
||||
2. Configure `.mosaic/orchestrator/config.json`:
|
||||
- set `"enabled": true`
|
||||
- set `"worker.command_template"` to your OpenCode worker command
|
||||
3. Queue work items in `.mosaic/orchestrator/tasks.json` (or via Matrix command ingestion).
|
||||
4. Run deterministic ticks:
|
||||
- `~/.mosaic/bin/mosaic-orchestrator-matrix-cycle`
|
||||
- `~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle`
|
||||
|
||||
This preserves rails enforcement (`quality_gates`) even without runtime-native subagent features.
|
||||
|
||||
Reference in New Issue
Block a user