build-company-ai-brain

name

build-company-ai-brain

description

Research a company on the public web, guide each important interview question with a quick-answer or supporting-source path, request appropriate business app connections, and create or update a source-backed company AI Brain with operating rules, provenance, team context, entity registries, workflows, and an automation backlog. Use when a user asks to build a company brain, Business Brain, organizational knowledge base, AI operating context, or reusable company workspace, especially when the result should lead to scheduled competitor analysis and a team skill shareable through GitHub or GitLab.

Build a Company AI Brain

Build a durable company-context workspace that agents can use without treating summaries as ground truth. Separate raw evidence, normalized company knowledge, task reasoning, and agent instructions.

Preserve the operating contract

• Treat the Brain as private by default.
• Read and draft freely within the approved workspace. Require explicit approval before sending, publishing, deleting, changing external systems, scheduling an automation, committing, pushing, or granting repository access.
• Keep raw sources immutable. Add new versions instead of silently rewriting evidence.
• Attach provenance, dates, confidence, and visibility to normalized facts.
• Preserve contradictions. Do not turn an inference into a canonical fact without review.
• Apply least privilege. Repository access does not imply permission to expose employee, customer, board, legal, or financial material.

Select the workflow

1. Existing Brain: inspect its instructions, orientation files, sources, and local changes; update only what the task requires.
2. Existing company repository or document set: auto-draft from available evidence and public research, then ask only unresolved questions.
3. No source material: ask for the company name and website, research public context, request useful read-only tool access, then continue the basic interview.
4. Advice only: provide the proposed structure and activation plan without writing files.

Resolve paths relative to this SKILL.md. For a new Brain, use scripts/scaffold_company_brain.py brain. For an accepted team-skill handoff, use scripts/scaffold_company_brain.py team-skill. Never run the Brain scaffold into a non-empty directory.

Phase 1: Investigate before interviewing

1. Read repository instructions such as AGENTS.md and README.md.
2. Scan filenames before reading broadly. Use rg to search exact names plus aliases, alternate spellings, products, customers, regions, and dates.
3. If the company name or website is known, research current public context before asking factual questions. Start with official sources and cite URLs and dates.
4. Inspect available apps, connectors, and tools. Identify which approved source would resolve the largest remaining gap and whether it is connected, available to connect, or unavailable.
5. Request access incrementally. State the tool, reason, intended search scope, technical permission footprint when known, read-only task boundary, and actions that will not be taken. Never ask the user to paste credentials into chat.
6. Use authorized sources to auto-draft context. Prefer original, direct, recent, and claim-specific evidence over summaries.
7. Record public claims, internal facts, inferences, and conflicts separately. Public marketing copy is not automatically internal truth.
8. Ask no question that the web, workspace, or approved connected sources already answer.

Read references/context-acquisition.md before web research or connector use. Read references/interview-and-evidence.md before interviewing or normalizing evidence. Read references/team-discovery.md before the team section.

Phase 2: Interview from basics to operations

Ask one concrete question at a time. Do not begin with an abstract decision, workflow, or automation question.

If the company identity is unknown, ask exactly:

What is the company's name and main website? If there is no public site, say “no website” and optionally give me a one-sentence description or a company overview document.

Then research before asking the next question. Present a short What I found publicly draft and ask the user to correct material errors.

For every high-value unanswered question, offer two practical response paths in the same turn:

1. Quick answer — show the shape of a sufficient one- or two-sentence answer, list, or blurb.
2. Use a source — suggest the single best available supporting source and the smallest useful document, folder, channel, query, project, or date range.

For example:

What are your top priorities for the next 6–12 months?

Quick answer: Give me a short blurb with the top one to three priorities and how success will be judged.

Use a source: If this is documented, connect Google Drive and point me to the specific strategy, OKR, or planning document. I will use that document for this question and show you a draft to correct.

Choose the source hint from the user's tools and the connectors actually available. Do not dump a catalog of apps into every question. Offer at most one primary source path and one upload/export fallback. If the user prefers to type, continue without making a connection mandatory.

Distinguish the intended search scope from the app's technical authorization scope. Never claim that connecting an app limits its permissions to one folder or channel unless the authorization flow truly enforces that. At the first request for each app, tell the user to review its permissions and state exactly what this task will and will not inspect.

Ask the remaining unanswered questions in this order:

1. what the company does;
2. products and services;
3. typical customers;
4. countries or regions served;
5. business model and how the company makes money;
6. most important offers and why customers choose them;
7. current priorities;
8. team size, departments, leaders, communication, operating rhythm, ownership, and future Brain users;
9. tools, source systems, important files, and access restrictions;
10. recurring work, manual pain, reports, and broken handoffs;
11. bounded automation opportunities and human approval;
12. competitors, monitoring needs, report owner, and cadence;
13. GitHub or GitLab ownership, visibility, reviewers, and maintenance.

Skip questions already answered by evidence. Ask the user to confirm consequential public findings instead of repeating them. Use references/interview-and-evidence.md for the guided question cards and sequencing.

For team discovery, build four layers progressively:

1. Formal structure — accept a headcount-and-functions blurb or use one named org chart, team directory, or handbook page from Google Drive, Notion, SharePoint, or Box.
2. Day-to-day communication — ask whether work happens in Slack, Teams, email, or elsewhere. Start with selected channel names, descriptions, and pinned guidance; inspect message history only for named channels and an approved date range. Exclude DMs and private channels by default.
3. Operating rhythm — accept a list of recurring meetings or use selected calendar series in a limited time window.
4. Ownership — map important outcomes, decisions, and handoffs to owners and approvers, using role charters, RACI documents, project systems, or user confirmation.

Do not infer reporting lines, authority, performance, or influence from message volume or meeting attendance. Present inferred team structure to the user for correction before making it canonical.

Before each high-value question, proactively suggest a useful source when one is likely to answer it. After every answer, also detect named context sources. If the user mentions a document system, chat, email, CRM, code host, meeting archive, spreadsheet, dashboard, or other repository:

1. check whether a matching connector or tool is already available and authorized;
2. if connected, inspect the narrow relevant scope before asking the next question;
3. if available but not connected, pause the questionnaire and ask to connect it using a specific read-only scope;
4. if unavailable, suggest the appropriate connector or ask for a focused export or upload;
5. use the acquired context to prefill the Brain and skip newly answered questions.

Also detect newly mentioned public entities, URLs, products, competitors, people, and markets. Research them before asking related follow-up questions, add dated findings to data/public-research.md, and ask the user only about what remains private, ambiguous, or unsupported.

After every five answers—or sooner when a section is complete—summarize:

• Confirmed — supported by a source or explicitly confirmed by the user;
• Inferred — a labelled working interpretation;
• Conflicts — claims that disagree and their sources;
• Open questions — missing context that matters;
• Files to update — proposed Brain artifacts.

Let the user correct the summary before promoting interview findings into canonical files. Preserve useful operator or customer wording verbatim when permitted.

Phase 3: Create the Brain

Create incrementally once the company identity, main offer and customer, initial source boundary, and confidentiality mode are known. Do not wait for perfect completeness.

For a new empty destination, run:

python3 <skill-dir>/scripts/scaffold_company_brain.py brain \
  --company "Company Name" \
  --output /path/to/company-brain

Then populate only supported content. Keep unknown fields explicit.

Maintain these layers:

1. README.md and AGENTS.md — purpose, orientation order, retrieval rules, permissions, and answer contract.
2. data/sources/ and data/interviews/ — raw or lightly processed evidence with source metadata.
3. data/source-manifest.yml — path, owner, visibility, event/export/ingestion dates, freshness, and status.
4. data/public-research.md — dated public-source findings, URLs, claims, inferences, and correction status.
5. data/overview.md, data/team-and-roles.md, and data/tools-and-sources.md — readable orientation, clearly labelled as interpretation.
6. data/registries/ — durable people, product, account, and metric entities with stable IDs and provenance.
7. data/workflows/, data/decisions/, and data/automation-backlog.md — operational knowledge and governed writeback targets.
8. data/competitors.md and data/competitive-reports/ — watchlist, aliases, relevance, confidence, dated intelligence, and uncertainty.
9. automations/competitor-analysis-spec.md — portable automation contract; keep runtime-specific schedule state outside the repository.

Use a normalized fact only when its source and status are clear. For material facts, prefer these fields:

entity_id, source, source_type, owner, visibility,
valid_from, valid_to, observed_at, last_verified,
supersedes, confidence

Distinguish event date, document date, export date, ingestion date, and artifact creation date when they differ.

Phase 4: Assess readiness

Before proposing automation, verify that the Brain contains enough context to answer:

• What does the company sell, to whom, and where?
• Which products, competitors, aliases, and substitute offerings matter?
• Which source files orient a new agent, and which sources are authoritative for each claim type?
• Who owns the report and what decision will it support?
• What information is restricted, stale, conflicting, or missing?

Proceed with labelled gaps when the user prefers a useful first version. Do not hide readiness risks.

Phase 5: Offer the three activation steps

Always finish a Brain build or substantial update with this concise activation offer:

1. Scheduled competitor analysis — propose a cadence, timezone, watchlist, research windows, trusted sources, report path, owner, delivery method, and approval boundary. Explain why the proposed cadence fits the market. Do not create the schedule until the user explicitly agrees.
2. Shareable company skill — propose .agents/skills/use-<company-slug>-brain/. Keep procedures, orientation paths, retrieval rules, and output expectations in the skill; keep private facts in the Brain itself.
3. Team sharing — recommend a private GitHub or GitLab repository by default, name owners and reviewers, list safe-to-commit files, and describe how teammates invoke the skill. Do not commit, push, or invite anyone without approval.

Include a short Ready now / Still needed list for each step.

Create the competitor automation only after approval

Read references/competitor-automation.md when drafting or creating the automation.

Require confirmation of:

• direct competitors, substitutes, discovery rules, and aliases;
• market, geography, product, and topic scope;
• cadence, local time, timezone, strict lookback, and rolling trend window;
• primary-source policy, citation requirements, and confidence labels;
• output path, same-day update behavior, audience, and delivery channel;
• alert thresholds, human review, restricted sources, and automation owner.

Use the product's automation mechanism when available. Never write a raw schedule directive as a substitute. Compare prior reports, update an existing same-date report, retain compact run memory, and say plainly when no material change occurred.

Create the shareable team skill only after approval

Read references/team-sharing.md before generating or publishing a team skill.

Run:

python3 <skill-dir>/scripts/scaffold_company_brain.py team-skill \
  --company "Company Name" \
  --brain-root /path/to/company-brain

Review the generated skill against the actual Brain paths. Keep it generic enough to share with authorized teammates and specific enough to enforce orientation, source checking, alias resolution, dates, contradictions, and file citations.

Validate every generated skill. If the current skill validator is available, run quick_validate.py against the folder. Otherwise verify that SKILL.md has only name and description in frontmatter, the folder matches the skill name, and agents/openai.yaml uses quoted strings with a default prompt that mentions $<skill-name>.

Complete the handoff

Report:

• the Brain path and files created or updated;
• confirmed context, conflicts, and consequential gaps;
• the proposed or installed competitor-analysis schedule;
• the team-skill path and privacy mode;
• validation performed;
• any action still requiring explicit user approval.