# Project Compass > Use when asked what to build next, whether to add something, or what is being missed; when a request adds another instance of a recurring pattern (another status, permission exception, option or workaround); when it locks in a data model or public contract; or when the repository keeps .project-compass/. Works out what the project is becoming, notices systems nobody defined and undecided business… - **Type:** Skill - **Install:** `agentstack add skill-soumyarauth-skills-hub-project-compass` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [soumyaRauth](https://agentstack.voostack.com/s/soumyarauth) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [soumyaRauth](https://github.com/soumyaRauth) - **Source:** https://github.com/soumyaRauth/skills-hub/tree/main/skills/project-compass - **Website:** https://soumyarauth.github.io/skills-hub/ ## Install ```sh agentstack add skill-soumyarauth-skills-hub-project-compass ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Project Compass One question, asked quietly before every non-trivial request and answered from this project rather than from general advice: > **Given everything I know about this project, what should this developer do > next, and why?** Usually the answer is *the thing they just asked for*, and the whole job is to build it well and say nothing. Sometimes it is not — and on those occasions the answer is worth more than the implementation would have been. The developer rarely knows that this is the question they are asking. That is the point of the skill. ``` "Implement X." │ ├─ literal reading → implement X │ └─ project reading → is X the right next step here, and if not, what happens before or instead of it? ``` This is never a refusal, and never a licence to substitute your own plan for theirs. It is the difference between an agent that executes requests and one that understands what is being built. ## What execution alone misses Coding agents execute well. Ask for search, a refactor, another permission check, a dashboard, and you get all of them, competently, one after another. Nobody in that loop is tracking the difference between: ``` ACTIVITY — features added, code refactored, endpoints optimized PROGRESS — the target problem solved, a real risk retired, a workflow completed ``` Or noticing that eight reasonable requests in a row have turned a user list into an administration system that nobody has designed, named, or decided to build. The person making the requests cannot see it, because they see one request at a time. This skill sees the sequence. ## Activation **Engage when** the user asks a direction question: *what next*, *should I add this*, *what am I missing*, *does this make sense*. Also engage when a request adds another instance of something already recurring (another status flag, another permission exception, another control on the same screen, another workaround), locks in something expensive to undo (a data model that will be populated, a public contract), or contradicts a recorded decision. Engage too when the repository keeps `.project-compass/`. **Stay quiet when** the request is small and local (a rename, copy, formatting, a dependency bump, a test fix), even in a drifting project. Also stay quiet during declared exploration. **Depth** `PASSIVE` by default: read the state, record what changed, say nothing. `CONSULT` is Mode B, one flag delivered with the work. `ACTIVE` is Mode C, or a direct question. Never `GATING`: even Mode C ends with the offer to build it as asked. **Composes with** `impact-map` (before the refactor a crossing calls for) · `standards-compass` (a crossing into identity, billing or personal data) · `api-contract-guard` (a request that fixes a public contract) · `architecture-engineer` (when the user wants a named crossing actually designed). This skill notices the missing model and names the decision; that one is what answers it, and only when asked. ### Working with the other Skills Hub skills - **Loaded is not engaged.** This file stays in context once loaded. Decide again on every new request whether it applies. Relevance to an earlier request carries nothing forward. Project state persists, and engagement does not. - **Depth.** `PASSIVE` informs judgment and adds nothing to the reply · `CONSULT` adds a few lines that change what gets built · `ACTIVE` shapes the work · `GATING` decides whether something proceeds, and only when a person asked for that decision. - **Announce once.** When any skill engages at `CONSULT` or above, open the reply with one line such as `⚡ Impact Map · Standards Compass — rename reaches report SQL; export carries personal data`: names and a few words of reason. Never include reasoning. Add no line for `PASSIVE`, and none on a trivial request. The line is a promise: every skill it names is loaded before the reply ends. If one turns out not to apply, say so in one line: ` dropped: `. - **One interruption per request.** Skills that must speak before the work share one short block. Everything else arrives with the work. - **Hand off; don't absorb.** When another discipline is needed, write `HANDOFF → : []` and let that skill do its part. When the request asked for that skill's decision, load it in the same turn and pass it your findings; a HANDOFF line alone does not answer the request. Never state another skill's verdict yourself. If it is not installed, do the smallest version of its check inline and say so. - **Conflicts.** User intent, then project context, then engineering risk, then applicable standards, then verification depth. Each skill keeps its own verdict, and none overrules another's. - **Overrides.** "Use X" engages X. "Skip X" or "no review" drops X's ceremony. Three things are never dropped: invented evidence, a check reported as run when it did not run, and a live hazard (a reachable security hole, data loss, money at risk). A live hazard is said once, in one line. - **State.** Read what sibling skills recorded (`.project-compass/`, `.project-standards/`, `.proofbuild/`, `.agent-investigation/`) rather than re-deriving it. Write only your own. - **Lessons.** On engaging, read `~/.skills-hub/lessons/.md` if it exists. When a person corrects this skill's work (a miss, a false alarm, a wrong verdict), or the work exposes a gap in this file that another project would hit too, append one line to it: `- YYYY-MM-DD · — `. Never write project names, paths, identifiers, code or data there; facts about one repository are project state. Keep at most 20 lines, merging or replacing one to add another. A lesson sharpens this file's checks and never overrides its rules or a person's instruction. The file sits outside every project, so no read-only rule covers it. Say `Lesson recorded: ` once; if the file cannot be written, give the lesson in the reply instead. ## Non-negotiable rules 1. **Never invent the project's purpose, users, market, deadlines, metrics, or stakeholders.** If the objective is undocumented, *"there is no documented objective"* is the finding — a useful one. A fabricated goal poisons every recommendation built on it. 2. **Never fabricate history.** No invented past requests, commits, decisions, incidents, user feedback, or usage data. The trajectory is a record of what was actually observed, not a plausible story about it. 3. **Label every claim** `OBSERVED`, `INFERRED`, `ASSUMED`, or `UNKNOWN`, and give inferences a confidence. An inference stated as a fact is the same error as inventing one. 4. **Patterns need evidence you can point at.** "Three permission exceptions" is a claim about three specific locations. Name them or drop the finding. 5. **Do not manufacture a gap.** Every project has undefined things. A gap worth naming is one that is *already blocking or distorting work in progress* — the rest are just facts about software. 6. **Every finding ends in an action.** *"There is no order lifecycle"* is an observation and it is not finished. *"Define the order lifecycle before adding a fifth status"* is the deliverable. If a finding cannot be turned into a next step smaller than the work it prevents, it is not ready to say. 7. **Take the developer's stated intent as fact.** *"I know this isn't ideal, I'm experimenting"* · *"this is a throwaway prototype"* · *"we've already decided"* — each of those settles the matter. Record it and adjust every later recommendation to the goal they stated, not to your preferred engineering philosophy. 8. **A dismissed observation is closed.** When the user says it is intentional, record it as a decision and never raise it again unless new evidence changes the consequence. Repeating a rejected point is how a useful skill becomes an uninstalled one. 9. **Never block ordinary work.** A rename is a rename. Even Mode C ends with *"and I can still do it your way"* — the user decides. 10. **Never report your own activity.** No "I read your trajectory file", no "analyzing the project". The intelligence shows up as a better answer, not as narration. 11. **State is a cache, not truth.** The repository outranks `.project-compass/`. Re-verify any recorded claim before building a recommendation on it, and correct the file when it has gone stale. 12. **Recommend the non-coding action when it is the right one** — define a rule, measure the thing, ship it and watch, ask a user, delete the feature. The goal is progress, not code produced. ## What the model holds Built continuously from evidence, not from a questionnaire, and never all at once: ``` identity what this software currently is purpose what problem it appears to solve users who appears to use it core workflows the paths that have to work end to end domain the concepts, their relationships, their lifecycles recent work what the developer has actually been building direction what it appears to be becoming decisions what has already been settled assumptions what is being taken as true, unverified open questions what is still undefined and is affecting implementation gaps where the project is, versus where it evidently needs to be next action the single most useful thing to do about all of the above ``` The last three lines are the output. The rest exist to make them trustworthy. What each dimension is, what evidence establishes it, and the reading order that gets there fastest: `references/project-model.md`. ### Four lenses, one answer The model is read through four lenses, because a project's real next step is as often a product or domain question as an engineering one: | | Reads for | | --- | --- | | **Product** | What each feature is for · who asked · whether the workflow completes · complexity nobody needed · value nobody has stated | | **Business** | The rules the code encodes · operational burden being created · what a customer already depends on · what breaks a process rather than a test | | **Domain** | Entities, relationships, lifecycles, invariants, ownership, and the vocabulary the team actually uses | | **Engineering** | Architecture, coupling, duplication, boundaries, data model, APIs, tests, performance, reliability, security | **Do not produce a report on the four.** They are inputs to one question — what should this developer do next — and the answer is a sentence, not a survey. When they disagree about the next step, the ranking in Step 5 settles it, and it does not put engineering first by default. ## Evidence model Every line carries one of four labels. Four, because the difference between them is exactly the difference between advice worth taking and advice worth ignoring. | | Meaning | Must carry | | --- | --- | --- | | `OBSERVED` | Read directly — code, schema, config, docs, a commit, the user's own words | Where it was read | | `INFERRED` | Concluded from observations, with **High** or **Low** confidence | Which observations, and what would overturn it | | `ASSUMED` | Taken as true to make progress, unverified | What breaks if it is wrong | | `UNKNOWN` | Established as not known | What would settle it | ``` Users belong to exactly one organization INFERRED (High) from: schema — users.organization_id is non-null with no join table; every query in src/repo/*.ts filters on it overturned by: any membership table, or a user seen in two orgs ``` Prefer evidence in this order: an explicit statement by the user · documentation and ADRs · the schema · the code · git history · configuration · the shape of the UI · inference from all of it. Never let inference overrule a stated fact, and never let a stale document overrule the schema. See `references/evidence-model.md`. ## The project state Persisted state is what separates this skill from asking an agent *"what am I missing?"* — that question gets a fresh guess every time, from nothing. This accumulates, and its purpose is **better guidance later**, not a record of what happened. ``` .project-compass/ ├── project.md what this is, who it serves, what it must do — labeled ├── direction.md what it is becoming, the biggest gap, the next step ├── trajectory.md dated entries: what changed, and which pattern it fed ├── decisions.md settled questions, including "we discussed this, proceed" ├── open-questions.md unresolved decisions that are affecting implementation └── blind-spots.md gaps that cleared the bar, and what closes them ``` `direction.md` is the one that earns its keep fastest, because it is the file that answers *what should I do next* without re-deriving anything: ```markdown # Direction **Appears to be** A team task tracker with an increasingly capable list view **Becoming** A saved-query / list-management workflow INFERRED (High) **Key workflow** create → assign → complete. Assign and complete both work; nothing closes the loop — no detail view, no comments **Biggest gap** Nobody has said who the list screen is for, and three features already disagree about what a task is on it **Next step** One sentence naming the user and the job of that screen, before the eighth control goes on it **Why** Export is the second feature in a row that needs to know which fields matter, and there is no answer **Confidence** High for the pattern, Low for whether it is deliberate **Evidence** CHANGELOG 0.5.0–0.9.0; TaskFilters.jsx:3 (4 fields), SavedViews.jsx:4 (2), api/tasks.js:3 (3) **Verified** 2026-09-10 ``` Create only what carries state. A first session usually writes `project.md` and nothing else; `direction.md` appears when there is a direction worth recording, and `blind-spots.md` may never exist at all — that is a healthy project, not a failed run. **Read the directory before answering anything.** It costs one pass and it is the entire point. If it does not exist, the project state is `FORMING`: build what the repository supports, say what you do not know, and do not compensate with confident guesses. **Creating it is the only write this skill makes** outside the work that was asked for. Create it on the first session with something worth recording, say so in one line — *"noting what I've worked out about this project in `.project-compass/`"* — and never mention it again. If the user would rather not have it, keep the model in the session and say nothing further. Never write anything else anywhere, and never put secrets, customer data, or opinions about people into these files. Formats, update triggers, size budgets, staleness handling, and what must never go in: `references/project-state.md`. ## Engineering state One of four, recorded in `project.md`, re-evaluated when the evidence moves. | State | What it means | Behavior | | --- | --- | --- | | `FORMING` | Not enough evidence yet to have a view | Work, observe, record. Do not diagnose a project you have just met | | `DIRECTED` | Requests fit together and support a coherent objective | Stay out of the way | | `EXPLORATORY` | Deliberate investigation — prototypes, spikes, comparisons | Help explore. Gap detection is **off** for the area under exploration | | `DRIFTING` | Implementation is accumulating away from any coherent objective, on evidence | Guide, once, with the evidence | `EXPLORATORY` is set by the user's own signals ("let's try", "prototype", "benchmark these", "throwaway") and by the artifacts of exploration. It ends when the user chooses, or when exploration output starts being extended rather than replaced — at which point the choice being made permanent is worth one line. See `references/drift-detection.md`. --- # The ch … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [soumyaRauth](https://github.com/soumyaRauth) - **Source:** [soumyaRauth/skills-hub](https://github.com/soumyaRauth/skills-hub) - **License:** MIT - **Homepage:** https://soumyarauth.github.io/skills-hub/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-soumyarauth-skills-hub-project-compass - Seller: https://agentstack.voostack.com/s/soumyarauth - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.