| name | harbor-context-refresh |
| description | Use when refreshing Harbor generated context under .harbor/views/**, including project structure, L2 README, Module Capsule, stale checks, doctor checks, or finish --sync-context after code, contract, schema, CLI, JSON, test, DDT, or module boundary changes. |
Harbor Context Refresh Skill
Version: Harbor-spec v1.3.0
Purpose: Generated context refresh workflow for Harbor-managed repositories
1. Purpose
Use this skill when generated Harbor context may need to be refreshed.
Generated context lives under:
.harbor/views/**
Generated context helps humans and AI agents understand the repository efficiently.
It includes:
project structure
L2 README
Module Capsule
module-card
review-checklist
debug-playbook
This skill ensures that generated context reflects the current source of truth.
This skill is an on-demand workflow entrypoint.
It is not source of truth.
It must follow:
AGENTS.md
.harbor/policy.yaml
.harbor/safety.yaml
.harbor/rules/agent-policy.md
.harbor/rules/contract-rules.md
.harbor/rules/ddt-rules.md
.harbor/rules/runtime-safety.md
.harbor/rules/diary-rules.md
.harbor/rules/project-rules.md, if present
Core principle:
Generated context should summarize the source of truth, not replace it.
2. When to Use
Use this skill after changes that may affect:
module boundaries
project structure
public contracts
docstrings
schemas
tests / DDT
CLI behavior
JSON output
file write behavior
workspace structure
module responsibilities
debug workflow
review workflow
generated context format
Typical triggers:
code changed in a meaningful module
contract changed
schema changed
public CLI behavior changed
JSON output changed
tests or DDT bindings changed
module moved or renamed
new module added
module responsibility changed
Module Capsule may be stale
L2 README may be stale
project structure may be stale
finish --sync-context is needed
stale check reports outdated views
doctor reports generated context warning
Do not use this skill for trivial edits that do not affect generated context.
3. Boundary With AGENTS.md, Project Rules, and Other Skills
3.1 AGENTS.md
AGENTS.md is the lightweight cross-tool entrypoint.
Use it for:
global role
workspace boundaries
default workflow
instruction priority
context loading order
completion expectations
Do not duplicate all AGENTS rules inside this skill.
3.2 Project Rules
Project-specific rules live in:
.harbor/rules/project-rules.md
Use Project Rules for:
project-specific module boundaries
verified test commands
strictness map
project-specific generated context expectations
local refresh conventions
If this skill conflicts with Project Rules, inspect .harbor/policy.yaml and .harbor/safety.yaml.
Machine policy wins over Markdown rules.
3.3 Related Skills
Use related skills when needed:
harbor-contract-change
Use when context refresh follows or reveals Contract Impact.
harbor-code-review
Use when reviewing whether generated context is stale after code changes.
harbor-ddt-diary
Use when refresh follows DDT changes, l3_version changes, or Diary-relevant decisions.
harbor-safety-preflight
Use before broad generated writes, protected path changes, .harbor/*.yaml changes, or generated skill writes.
harbor-workspace-migration-plan
Use when refresh involves workspace layout, migration dry-run, cleanup planning, or canonical workspace changes.
This skill may route to these skills, but should not replace them.
4. Canonical Generated Context
Canonical generated context lives under:
.harbor/views/
Expected layout:
.harbor/views/
project-structure.md
l2/
_meta.json
<module>/
README.md
modules/
<module>/
module-card.md
review-checklist.md
debug-playbook.md
Meaning:
.harbor/views/project-structure.md
repository-level generated context
.harbor/views/l2/<module>/README.md
module-level L2 README
.harbor/views/modules/<module>/module-card.md
concise module identity and responsibility summary
.harbor/views/modules/<module>/review-checklist.md
module-specific review checklist
.harbor/views/modules/<module>/debug-playbook.md
module-specific debugging guide
5. Source-of-Truth Boundary
Generated context is not source of truth.
Treat these as source of truth:
source code
tests
schemas
type definitions
configuration
public CLI behavior
public JSON output
human-authored project docs
.harbor/diary/**
.harbor/policy.yaml
.harbor/safety.yaml
Treat these as generated context:
.harbor/views/**
Treat these as external workflow exports:
.agents/skills/**
Rules:
Do not manually edit .harbor/views/** as project truth.
Do not let generated context override code, contracts, schemas, tests, policy, or diary.
If generated context conflicts with source of truth, treat generated context as stale.
Refresh generated context through Harbor commands.
6. Runtime Safety Boundary
Refreshing generated context usually writes files under:
.harbor/views/**
This is usually medium risk.
Use harbor-safety-preflight when:
refresh scope is broad
write targets are unclear
refresh touches unexpected paths
refresh may overwrite user-authored content
refresh affects .harbor/rules/**
refresh affects .harbor/*.yaml
refresh affects .agents/skills/**
refresh involves workspace layout changes
refresh involves migration or cleanup
Do not manually rewrite generated context.
Do not write outside expected generated context paths unless the user explicitly requests it.
7. Step 1: Identify Refresh Trigger
Classify the trigger.
Possible triggers:
code change
contract change
schema change
test / DDT change
CLI change
JSON output change
module boundary change
project structure change
workspace layout change
generated context stale warning
doctor warning
manual user request
unknown
If trigger is unknown, inspect relevant source, tests, and Harbor views before writing.
8. Step 2: Identify Refresh Scope
Classify refresh scope as one of:
NONE
PROJECT_STRUCTURE
SINGLE_L2
CHANGED_L2
ALL_L2
SINGLE_MODULE_CAPSULE
CHANGED_MODULE_CAPSULES
ALL_MODULE_CAPSULES
SYNC_CONTEXT
STALE_CHECK_ONLY
DOCTOR_CHECK_ONLY
WORKSPACE_DIAGNOSTICS
Guidance:
NONE
No generated context update needed.
PROJECT_STRUCTURE
Repository layout, module layout, workspace layout, or command organization changed.
SINGLE_L2
One module’s L2 README needs refresh.
CHANGED_L2
Changed modules’ L2 README files need refresh.
ALL_L2
Major architecture or layout change affects all modules.
SINGLE_MODULE_CAPSULE
One module’s capsule needs refresh.
CHANGED_MODULE_CAPSULES
Changed modules’ capsules need refresh.
ALL_MODULE_CAPSULES
Major architecture or module framework change affects all capsules.
SYNC_CONTEXT
Use finish --sync-context to refresh changed L2 README and Module Capsule together.
STALE_CHECK_ONLY
Only inspect whether generated context is stale.
DOCTOR_CHECK_ONLY
Only inspect Harbor workspace health.
WORKSPACE_DIAGNOSTICS
Use workspace inspect or migrate dry-run; not a default coding workflow.
Prefer the narrowest scope that satisfies the task.
9. Step 3: Inspect Existing Context
Before writing generated context, inspect what currently exists.
Relevant files:
.harbor/views/project-structure.md
.harbor/views/l2/<module>/README.md
.harbor/views/modules/<module>/module-card.md
.harbor/views/modules/<module>/review-checklist.md
.harbor/views/modules/<module>/debug-playbook.md
Also inspect relevant source of truth:
source files
tests
schemas
DDT targets
policy
diary
project rules
Do not refresh based only on stale generated context.
Refresh should reflect source of truth.
10. Step 4: Choose Commands
Use the appropriate Harbor command.
10.1 Project Structure
harbor project structure --write
Use when:
repository layout changed
module layout changed
workspace layout changed
major command organization changed
10.2 Single L2 README
harbor docs --module <module> --write
Use when:
one module changed
one module’s contract or responsibility changed
one module’s L2 README is stale
10.3 Changed L2 README
harbor docs --changed --write
Use when:
changed modules need L2 refresh
task touched multiple modules
finish flow needs refreshed module summaries
10.4 All L2 README
harbor docs --all --write
Use when:
major architecture changed
workspace-wide module summary format changed
all module summaries need regeneration
Use with caution.
Broad generated writes may require safety preflight.
10.5 Single Module Capsule
harbor module seal <module> --write
Use when:
one module capsule needs refresh
module-card / review-checklist / debug-playbook may be stale
10.6 Changed Module Capsules
harbor module seal --changed --write
Use when:
changed modules need Module Capsule refresh
10.7 All Module Capsules
harbor module seal --all --write
Use when:
major architecture changed
capsule format changed
all module capsules need regeneration
Use with caution.
Broad generated writes may require safety preflight.
10.8 Task-level Sync
harbor finish --sync-context
Use when:
task is ending
changed L2 README and Module Capsule should be refreshed together
implementation / contract / tests changed
This is the preferred task-level context sync command.
10.9 Stale Check
harbor stale
harbor stale --format json
Use when:
checking whether generated context is stale
validating generated context after refresh
preparing final response
10.10 Doctor Check
harbor doctor
harbor doctor --format json
Use when:
checking overall Harbor health
validating workspace status
preparing release-like confidence
10.11 Workspace Diagnostics
harbor workspace inspect
harbor workspace inspect --format json
harbor workspace migrate --dry-run
harbor workspace migrate --dry-run --format json
Use when:
workspace layout is involved
managed files are unclear
migration or cleanup is being planned
canonical workspace health is being inspected
harbor workspace migrate --dry-run is read-only.
It is not part of the default coding workflow.
Do not assume harbor workspace migrate --write exists.
11. Step 5: Run Stale Check
After a generated context refresh, run or recommend:
harbor stale
For machine-readable output:
harbor stale --format json
Interpretation:
PASS:
generated context appears up to date.
WARN:
generated context may be stale or partially missing.
FAIL:
generated context is outdated or inconsistent enough to block confidence.
SKIP:
check could not run due to missing prerequisites.
If stale warnings remain, report them.
Do not claim stale check passed unless it actually ran and passed.
12. Step 6: Run Doctor Check
After meaningful generated context work, run or recommend:
harbor doctor
For machine-readable output:
harbor doctor --format json
Doctor may inspect:
workspace health
policy files
generated context
DDT status
skill references
runtime safety
configuration issues
If doctor warnings remain, report them.
Do not claim doctor passed unless it actually ran and passed.
13. Step 7: Check Contract and DDT Implications
Generated context refresh may reveal contract or DDT issues.
Route to harbor-contract-change when:
generated context shows stale contract summary
contract source changed
public behavior changed
CLI / JSON output changed
file write behavior changed
workspace behavior changed
Route to harbor-ddt-diary when:
tests or DDT bindings changed
l3_version changed
fixtures or snapshots changed
Diary Draft is needed
Route to harbor-code-review when:
generated context and implementation disagree
review-checklist identifies drift
debug-playbook points to outdated behavior
14. Step 8: Check Diary Need
A simple generated context refresh usually does not need Diary.
Diary may be needed when the refresh reflects or accompanies:
Contract Change
Breaking Change
workspace layout change
generated context schema change
Module Capsule structure change
L2 README semantics change
project structure generation rule change
agent context loading strategy change
important architecture decision
release-relevant decision
Canonical Diary path:
.harbor/diary/YYYY-MM.jsonl
Do not run:
harbor log
unless the user explicitly requests it.
If Diary is needed but not written, output a Diary Draft.
15. Step 9: Explicit User Request Only
Do not run the following unless the user explicitly requests it:
harbor log
harbor accept
harbor lock
harbor module promote-skill <module>
Meaning:
harbor log
writes Diary / decision memory
harbor accept
accepts new Harbor baseline
harbor lock
legacy or lock-style baseline operation
harbor module promote-skill <module>
exports a Module Capsule into an external AI skill
Never run harbor accept merely to silence unresolved drift.
Never run harbor module promote-skill as part of ordinary context refresh.
16. Step 10: Output Result
Return:
Context Refresh Summary:
- Trigger:
- Refresh scope:
- Commands run:
- Generated views changed:
- Stale result:
- Doctor result:
- Contract / DDT implications:
- Runtime safety:
- Diary:
- Remaining stale views:
- Remaining risks:
- Recommended next command:
If commands were not run, state clearly:
未实际运行 Harbor 命令。建议执行：
<command>
Do not invent command results.
17. Tool Honesty
Do not claim the following were run unless actually run and observed:
harbor project structure --write
harbor docs --changed --write
harbor docs --all --write
harbor module seal --changed --write
harbor finish --sync-context
harbor stale
harbor doctor
harbor workspace inspect
harbor workspace migrate --dry-run
Allowed wording:
已运行，结果是...
未运行，建议运行...
当前环境无法运行...
我只做了静态审查，未执行命令...
Forbidden wording when not executed:
stale check 已通过
doctor 通过
context 已同步
capsule 已刷新
unless actually observed.
18. Review Labels
When reviewing context refresh needs, use these labels:
Generated Context Gap
Stale L2 README
Stale Module Capsule
Stale Project Structure
Missing Generated View
Unexpected Generated Write
Manual Generated Edit Risk
Workspace Context Risk
Suggested Refresh
Definitions:
Generated Context Gap:
Generated context may not reflect source of truth.
Stale L2 README:
.harbor/views/l2/<module>/README.md is outdated.
Stale Module Capsule:
module-card, review-checklist, or debug-playbook is outdated.
Stale Project Structure:
.harbor/views/project-structure.md is outdated.
Missing Generated View:
Expected generated context file is missing.
Unexpected Generated Write:
A command may write outside expected generated context paths.
Manual Generated Edit Risk:
Generated context was manually edited as if it were source of truth.
Workspace Context Risk:
Workspace layout or generated context path behavior changed without governance.
Suggested Refresh:
Non-blocking recommendation to refresh context.
19. Common Mistakes
Avoid:
manually editing .harbor/views/** as project truth
refreshing generated context before updating source of truth
using stale generated context to override implementation
using stale generated context to override schema
using stale generated context to override tests
running broad --all refresh without need
claiming stale / doctor passed without running them
running harbor accept to hide stale context
running harbor module promote-skill during ordinary context refresh
treating .agents/skills/** as canonical context
treating .harbor/cache/** or .harbor/state/** as source of truth
20. Final Principle
Before refreshing generated context, ask:
What changed in the source of truth?
Which generated view summarizes that change?
What is the narrowest safe refresh command?
How will stale / doctor verify the result?
A good context refresh makes future AI work easier without turning generated views into source of truth.
